Replace background task spinner with gear

Use an outlined settings gear with a running-count badge and slow linear rotation while background tasks are active. Preserve reduced-motion behavior, composer sizing, and tooltip coverage with updated focused tests and notes.
This commit is contained in:
2026-11-12 12:43:47 +00:00
parent 0bb3a5c5c6
commit a2a9a7e3c1
7 changed files with 332 additions and 224 deletions
@@ -5,7 +5,7 @@ import 'package:flutter/material.dart';
import '../../../core/api_gateway.dart';
import 'chat_background_tasks_controller.dart';
import 'chat_background_tasks_dialog.dart';
import 'chat_task_spinner.dart';
import 'chat_task_gear.dart';
/// Compact live task count: a quiet control inside the composer beside Send,
/// shown only while tasks run. Details live only in its modal.
@@ -147,11 +147,11 @@ class _ChatBackgroundTasksState extends State<ChatBackgroundTasks> {
visualDensity: VisualDensity.compact,
),
onPressed: _open,
// A ring around the running count while tasks run; automations stay
// A turning gear with a count badge while tasks run; automations stay
// on their static schedule icon.
icon: automationOnly
? const Icon(Icons.schedule, size: 16)
: ChatTaskSpinner(running: count),
: ChatTaskGear(running: count),
label: caption(),
);
return Padding(
@@ -0,0 +1,87 @@
import 'package:flutter/material.dart';
/// Background-task glyph for the composer: an outlined settings gear. While
/// [running] is above zero the gear turns slowly and steadily (linear, one
/// turn per [turnDuration]) and a small Material [Badge] shows the count.
/// With no running task the gear is static and carries no badge. With reduced
/// motion the gear never rotates but the badge still shows. Always [size]
/// square so the button keeps the same dimensions in every state.
class ChatTaskGear extends StatefulWidget {
const ChatTaskGear({super.key, required this.running, this.size = 16});
final int running;
final double size;
/// Time for one full turn while tasks run.
static const Duration turnDuration = Duration(seconds: 4);
@override
State<ChatTaskGear> createState() => _ChatTaskGearState();
}
class _ChatTaskGearState extends State<ChatTaskGear>
with SingleTickerProviderStateMixin {
late final AnimationController _spin = AnimationController(
vsync: this,
duration: ChatTaskGear.turnDuration,
);
bool? _spinning;
@override
void didChangeDependencies() {
super.didChangeDependencies();
_sync();
}
@override
void didUpdateWidget(covariant ChatTaskGear oldWidget) {
super.didUpdateWidget(oldWidget);
_sync();
}
/// Turns the gear only while tasks run and motion is allowed. Stopping
/// resets to the upright position, so an idle gear is always the same glyph.
void _sync() {
final reduced = MediaQuery.maybeDisableAnimationsOf(context) ?? false;
final spinning = widget.running > 0 && !reduced;
if (spinning == _spinning) return;
_spinning = spinning;
if (spinning) {
_spin.repeat();
} else {
_spin.stop();
_spin.value = 0;
}
}
@override
void dispose() {
_spin.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
final theme = Theme.of(context);
final running = widget.running;
return SizedBox.square(
key: const Key('chat-background-tasks-gear'),
dimension: widget.size,
child: Badge(
key: const Key('chat-background-tasks-badge'),
isLabelVisible: running > 0,
backgroundColor: theme.colorScheme.primary,
textColor: theme.colorScheme.onPrimary,
label: Text(
'$running',
key: const Key('chat-background-tasks-count'),
),
child: RotationTransition(
key: const Key('chat-background-tasks-rotation'),
turns: _spin,
child: Icon(Icons.settings_outlined, size: widget.size),
),
),
);
}
}
@@ -1,50 +0,0 @@
import 'package:flutter/material.dart';
/// Background-task glyph for the composer. While [running] is above zero it
/// shows a thin Material progress ring around the count; with reduced motion
/// the ring holds one static quarter segment instead of spinning. With no
/// running task it is the plain layers icon, with no ring. Always [size] square
/// so the button keeps the same dimensions in every state.
class ChatTaskSpinner extends StatelessWidget {
const ChatTaskSpinner({super.key, required this.running, this.size = 16});
final int running;
final double size;
/// Fraction of the ring drawn while reduced motion holds it still.
static const double reducedSegment = 0.25;
@override
Widget build(BuildContext context) {
final theme = Theme.of(context);
final reduced = MediaQuery.maybeDisableAnimationsOf(context) ?? false;
final content = running > 0
? Stack(
alignment: Alignment.center,
children: [
SizedBox.square(
dimension: size,
child: CircularProgressIndicator(
strokeWidth: 2,
color: theme.colorScheme.primary,
value: reduced ? reducedSegment : null,
),
),
FittedBox(
fit: BoxFit.scaleDown,
child: Text(
'$running',
key: const Key('chat-background-tasks-count'),
style: theme.textTheme.labelSmall,
),
),
],
)
: Icon(Icons.layers_outlined, size: size);
return SizedBox.square(
key: const Key('chat-background-tasks-spinner'),
dimension: size,
child: content,
);
}
}
+45
View File
@@ -0,0 +1,45 @@
# gear-icon-background-tasks — composer gear replaces the count ring
## What changed
The composer's background-tasks control now shows an outlined settings gear
(`Icons.settings_outlined`) instead of the progress ring with a count. While tasks
run the gear turns linearly, one turn per 4 s, and a Material `Badge` shows the
running count. When nothing runs the gear is upright, static and has no badge.
Reduced motion keeps the badge but never rotates the gear. Button size (16 px
square) and tooltip (`Background tasks (N running)`) are unchanged.
| File | Change |
| --- | --- |
| `lib/features/chat/conversation/chat_task_gear.dart` | New `ChatTaskGear` widget (replaces `chat_task_spinner.dart`, deleted) |
| `lib/features/chat/conversation/chat_background_tasks.dart` | Uses `ChatTaskGear`; comment updated |
| `test/features/chat/conversation/chat_task_gear_test.dart` | Renamed from `chat_task_spinner_test.dart`; rewritten for gear, badge, rotation, reduced motion, dark, size, composer tooltip |
| `test/features/chat/conversation/chat_background_tasks_test.dart` | Comment only: the count now sits on the badge; expectations unchanged |
## Behaviour
- `running > 0` and motion allowed: `AnimationController.repeat()` over
`ChatTaskGear.turnDuration` (4 s), linear, bound to `RotationTransition`.
- `running == 0`, or reduced motion: no ticker; a stop resets the turn to 0.
- Badge: `isLabelVisible: running > 0`, theme primary background and `onPrimary` text.
- Keys: `chat-background-tasks-gear` (box), `chat-background-tasks-badge`,
`chat-background-tasks-rotation`, `chat-background-tasks-count` (badge label).
- Automation-only state still shows the static `Icons.schedule` (unchanged).
## Focused results
Command: `tool/memwatch/full.sh 'test/features/chat/conversation/chat_task_gear_test.dart test/features/chat/conversation/chat_background_tasks_test.dart test/features/chat/conversation/chat_background_tasks_modal_test.dart test/features/chat/conversation/chat_automation_lifecycle_test.dart test/features/chat/conversation/chat_background_task_metadata_test.dart'`
Verdict: PASS, 34 passed, 0 failed, 0 skipped, peak 1167 MB, 5 s, exit 0.
`tool/analyze.sh`: clean, exit 0.
A first run failed because `_sync()` read `MediaQuery` from `initState`; it was
moved to `didChangeDependencies` (which runs after `initState`). The rerun is the
result above.
## Not verified here
- No light/dark captures and no visual check of the 16 px badge overlap. Owned by ui-review.
- No on-device check.
- The land gate has not been run.
@@ -675,7 +675,7 @@ void main() {
await tester.pump(const Duration(milliseconds: 500));
expect(find.byTooltip('Background tasks (2 running)'), findsOneWidget);
final counter = find.byKey(const Key('chat-background-tasks-button'));
// One '2' is the count inside the ring, one is the compact caption.
// One '2' is the count on the gear badge, one is the compact caption.
expect(
tester
.widget<Text>(find.byKey(const Key('chat-background-tasks-count')))
@@ -0,0 +1,196 @@
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/chat/conversation/chat_background_tasks.dart';
import 'package:pipelines_app/features/chat/conversation/chat_task_gear.dart';
final _gearFinder = find.byKey(const Key('chat-background-tasks-gear'));
final _badgeFinder = find.byKey(const Key('chat-background-tasks-badge'));
final _rotationFinder = find.byKey(const Key('chat-background-tasks-rotation'));
RotationTransition _rotation(WidgetTester tester) =>
tester.widget<RotationTransition>(_rotationFinder);
Badge _badge(WidgetTester tester) => tester.widget<Badge>(_badgeFinder);
Widget _gear(int running, {Brightness brightness = Brightness.light}) =>
MaterialApp(
theme: ThemeData(colorSchemeSeed: Colors.indigo, brightness: brightness),
home: Scaffold(
body: Center(child: ChatTaskGear(running: running)),
),
);
void _reducedMotion(bool reduced) =>
TestWidgetsFlutterBinding.ensureInitialized()
.platformDispatcher
.accessibilityFeaturesTestValue = FakeAccessibilityFeatures(
disableAnimations: reduced,
);
class _TasksGateway implements ApiGateway {
final _frames = StreamController<JsonMap>.broadcast();
List<JsonMap> running = const [];
@override
Stream<JsonMap> get frames => _frames.stream;
@override
Future<JsonMap> call(String type, [JsonMap fields = const {}]) async {
if (type == 'chat_shells') return {'chat_shells': running};
if (type == 'chat_automations') {
return {
'chat_automations': {'status': 'unavailable'},
};
}
return <String, dynamic>{};
}
void close() => _frames.close();
}
void main() {
tearDown(() => _reducedMotion(false));
testWidgets('a running task shows the outlined gear with a count badge', (
tester,
) async {
_reducedMotion(false);
await tester.pumpWidget(_gear(2));
expect(_badge(tester).isLabelVisible, isTrue);
expect(
find.descendant(of: _gearFinder, matching: find.text('2')),
findsOneWidget,
);
expect(
find.descendant(
of: _gearFinder,
matching: find.byIcon(Icons.settings_outlined),
),
findsOneWidget,
);
expect(
find.descendant(
of: _gearFinder,
matching: find.byIcon(Icons.layers_outlined),
),
findsNothing,
);
expect(tester.binding.transientCallbackCount, greaterThan(0));
await tester.pumpWidget(const SizedBox.shrink());
expect(tester.binding.transientCallbackCount, 0);
});
testWidgets('the running gear turns linearly, one turn per four seconds', (
tester,
) async {
_reducedMotion(false);
await tester.pumpWidget(_gear(1));
expect(_rotation(tester).turns.value, closeTo(0, 1e-9));
await tester.pump(const Duration(seconds: 1));
expect(_rotation(tester).turns.value, closeTo(0.25, 1e-3));
await tester.pump(const Duration(seconds: 1));
expect(_rotation(tester).turns.value, closeTo(0.5, 1e-3));
await tester.pump(const Duration(seconds: 2));
expect(_rotation(tester).turns.value, closeTo(0, 1e-3));
expect(ChatTaskGear.turnDuration, const Duration(seconds: 4));
});
testWidgets('an idle gear is static with no badge and no animation', (
tester,
) async {
_reducedMotion(false);
await tester.pumpWidget(_gear(0));
expect(_badge(tester).isLabelVisible, isFalse);
expect(
find.descendant(
of: _gearFinder,
matching: find.byIcon(Icons.settings_outlined),
),
findsOneWidget,
);
expect(tester.binding.transientCallbackCount, 0);
await tester.pump(const Duration(seconds: 1));
expect(_rotation(tester).turns.value, closeTo(0, 1e-9));
});
testWidgets('stopping the last task halts and resets the turn', (
tester,
) async {
_reducedMotion(false);
await tester.pumpWidget(_gear(2));
await tester.pump(const Duration(seconds: 1));
expect(_rotation(tester).turns.value, greaterThan(0));
await tester.pumpWidget(_gear(0));
expect(tester.binding.transientCallbackCount, 0);
expect(_rotation(tester).turns.value, closeTo(0, 1e-9));
expect(_badge(tester).isLabelVisible, isFalse);
});
testWidgets('reduced motion never rotates but still shows the count', (
tester,
) async {
_reducedMotion(true);
await tester.pumpWidget(_gear(3));
expect(tester.binding.transientCallbackCount, 0);
await tester.pump(const Duration(seconds: 2));
expect(_rotation(tester).turns.value, closeTo(0, 1e-9));
expect(tester.binding.transientCallbackCount, 0);
expect(_badge(tester).isLabelVisible, isTrue);
expect(
find.descendant(of: _gearFinder, matching: find.text('3')),
findsOneWidget,
);
});
testWidgets('the badge uses the theme primary in dark mode', (tester) async {
_reducedMotion(false);
await tester.pumpWidget(_gear(1, brightness: Brightness.dark));
final scheme = ColorScheme.fromSeed(
seedColor: Colors.indigo,
brightness: Brightness.dark,
);
expect(_badge(tester).backgroundColor, scheme.primary);
expect(_badge(tester).textColor, scheme.onPrimary);
});
testWidgets('every state keeps the same square size', (tester) async {
_reducedMotion(false);
for (final running in [0, 1, 12]) {
await tester.pumpWidget(_gear(running));
expect(tester.getSize(_gearFinder), const Size(16, 16));
}
});
testWidgets('the composer button shows the gear and its tooltip', (
tester,
) async {
_reducedMotion(false);
final gateway = _TasksGateway();
addTearDown(gateway.close);
gateway.running = const [
{'id': 'sh1', 'status': 'running', 'command': 'go test ./...'},
{'id': 'sh2', 'status': 'running', 'command': 'make'},
];
await tester.pumpWidget(
MaterialApp(
home: Scaffold(
body: ChatBackgroundTasks(gateway: gateway, sessionId: 's'),
),
),
);
// The gear turns forever while tasks run, so settle by pumping only.
await tester.pump();
await tester.pump();
expect(find.text('2 tasks'), findsOneWidget);
expect(find.byTooltip('Background tasks (2 running)'), findsOneWidget);
expect(_badge(tester).isLabelVisible, isTrue);
expect(
find.descendant(of: _gearFinder, matching: find.text('2')),
findsOneWidget,
);
expect(tester.binding.transientCallbackCount, greaterThan(0));
});
}
@@ -1,170 +0,0 @@
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/chat/conversation/chat_background_tasks.dart';
import 'package:pipelines_app/features/chat/conversation/chat_task_spinner.dart';
final _spinnerFinder = find.byKey(const Key('chat-background-tasks-spinner'));
CircularProgressIndicator _ring(WidgetTester tester) =>
tester.widget<CircularProgressIndicator>(
find.descendant(
of: _spinnerFinder,
matching: find.byType(CircularProgressIndicator),
),
);
Widget _spinner(int running, {Brightness brightness = Brightness.light}) =>
MaterialApp(
theme: ThemeData(colorSchemeSeed: Colors.indigo, brightness: brightness),
home: Scaffold(
body: Center(child: ChatTaskSpinner(running: running)),
),
);
void _reducedMotion(bool reduced) =>
TestWidgetsFlutterBinding.ensureInitialized()
.platformDispatcher
.accessibilityFeaturesTestValue = FakeAccessibilityFeatures(
disableAnimations: reduced,
);
class _TasksGateway implements ApiGateway {
final _frames = StreamController<JsonMap>.broadcast();
List<JsonMap> running = const [];
@override
Stream<JsonMap> get frames => _frames.stream;
@override
Future<JsonMap> call(String type, [JsonMap fields = const {}]) async {
if (type == 'chat_shells') return {'chat_shells': running};
if (type == 'chat_automations') {
return {
'chat_automations': {'status': 'unavailable'},
};
}
return <String, dynamic>{};
}
void close() => _frames.close();
}
void main() {
tearDown(() => _reducedMotion(false));
testWidgets(
'a running task shows an indeterminate primary ring with the count',
(tester) async {
_reducedMotion(false);
await tester.pumpWidget(_spinner(2));
final ring = _ring(tester);
expect(ring.value, isNull);
expect(ring.strokeWidth, 2);
expect(
ring.color,
ThemeData(colorSchemeSeed: Colors.indigo).colorScheme.primary,
);
expect(
find.descendant(of: _spinnerFinder, matching: find.text('2')),
findsOneWidget,
);
expect(
find.descendant(
of: _spinnerFinder,
matching: find.byIcon(Icons.layers_outlined),
),
findsNothing,
);
// The ring keeps turning: time advances the animation.
await tester.pump(const Duration(milliseconds: 300));
expect(tester.binding.transientCallbackCount, greaterThan(0));
await tester.pumpWidget(const SizedBox.shrink());
expect(tester.binding.transientCallbackCount, 0);
},
);
testWidgets('dark theme uses the dark primary for the ring', (tester) async {
_reducedMotion(false);
await tester.pumpWidget(_spinner(1, brightness: Brightness.dark));
expect(
_ring(tester).color,
ThemeData(
colorSchemeSeed: Colors.indigo,
brightness: Brightness.dark,
).colorScheme.primary,
);
});
testWidgets('no running task shows the static icon with no ring', (
tester,
) async {
_reducedMotion(false);
await tester.pumpWidget(_spinner(0));
expect(
find.descendant(
of: _spinnerFinder,
matching: find.byType(CircularProgressIndicator),
),
findsNothing,
);
expect(
find.descendant(
of: _spinnerFinder,
matching: find.byIcon(Icons.layers_outlined),
),
findsOneWidget,
);
expect(tester.binding.transientCallbackCount, 0);
});
testWidgets('every state keeps the same square size', (tester) async {
_reducedMotion(false);
for (final running in [0, 1, 12]) {
await tester.pumpWidget(_spinner(running));
expect(tester.getSize(_spinnerFinder), const Size(16, 16));
}
});
testWidgets('reduced motion holds one static ring segment while running', (
tester,
) async {
_reducedMotion(true);
await tester.pumpWidget(_spinner(3));
expect(_ring(tester).value, ChatTaskSpinner.reducedSegment);
await tester.pump(const Duration(seconds: 1));
expect(_ring(tester).value, ChatTaskSpinner.reducedSegment);
expect(tester.binding.transientCallbackCount, 0);
});
testWidgets('the composer button shows the count ring and its tooltip', (
tester,
) async {
_reducedMotion(false);
final gateway = _TasksGateway();
addTearDown(gateway.close);
gateway.running = const [
{'id': 'sh1', 'status': 'running', 'command': 'go test ./...'},
{'id': 'sh2', 'status': 'running', 'command': 'make'},
];
await tester.pumpWidget(
MaterialApp(
home: Scaffold(
body: ChatBackgroundTasks(gateway: gateway, sessionId: 's'),
),
),
);
// The ring repeats forever, so settle by pumping, never by waiting.
await tester.pump();
await tester.pump();
expect(find.text('2 tasks'), findsOneWidget);
expect(find.byTooltip('Background tasks (2 running)'), findsOneWidget);
expect(_ring(tester).value, isNull);
expect(
find.descendant(of: _spinnerFinder, matching: find.text('2')),
findsOneWidget,
);
});
}