From a2a9a7e3c1223744eaeeb65442a96437b0cd3ded Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 12 Nov 2026 12:43:47 +0000 Subject: [PATCH] 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. --- .../conversation/chat_background_tasks.dart | 6 +- .../chat/conversation/chat_task_gear.dart | 87 ++++++++ .../chat/conversation/chat_task_spinner.dart | 50 ----- app/notes/gear-icon-background-tasks.md | 45 ++++ .../chat_background_tasks_test.dart | 2 +- .../conversation/chat_task_gear_test.dart | 196 ++++++++++++++++++ .../conversation/chat_task_spinner_test.dart | 170 --------------- 7 files changed, 332 insertions(+), 224 deletions(-) create mode 100644 app/lib/features/chat/conversation/chat_task_gear.dart delete mode 100644 app/lib/features/chat/conversation/chat_task_spinner.dart create mode 100644 app/notes/gear-icon-background-tasks.md create mode 100644 app/test/features/chat/conversation/chat_task_gear_test.dart delete mode 100644 app/test/features/chat/conversation/chat_task_spinner_test.dart diff --git a/app/lib/features/chat/conversation/chat_background_tasks.dart b/app/lib/features/chat/conversation/chat_background_tasks.dart index c41e91e7..b21abead 100644 --- a/app/lib/features/chat/conversation/chat_background_tasks.dart +++ b/app/lib/features/chat/conversation/chat_background_tasks.dart @@ -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 { 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( diff --git a/app/lib/features/chat/conversation/chat_task_gear.dart b/app/lib/features/chat/conversation/chat_task_gear.dart new file mode 100644 index 00000000..f874911e --- /dev/null +++ b/app/lib/features/chat/conversation/chat_task_gear.dart @@ -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 createState() => _ChatTaskGearState(); +} + +class _ChatTaskGearState extends State + 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), + ), + ), + ); + } +} diff --git a/app/lib/features/chat/conversation/chat_task_spinner.dart b/app/lib/features/chat/conversation/chat_task_spinner.dart deleted file mode 100644 index 6b46e7fa..00000000 --- a/app/lib/features/chat/conversation/chat_task_spinner.dart +++ /dev/null @@ -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, - ); - } -} diff --git a/app/notes/gear-icon-background-tasks.md b/app/notes/gear-icon-background-tasks.md new file mode 100644 index 00000000..ea64682b --- /dev/null +++ b/app/notes/gear-icon-background-tasks.md @@ -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. diff --git a/app/test/features/chat/conversation/chat_background_tasks_test.dart b/app/test/features/chat/conversation/chat_background_tasks_test.dart index 3c515bd4..fdcdd262 100644 --- a/app/test/features/chat/conversation/chat_background_tasks_test.dart +++ b/app/test/features/chat/conversation/chat_background_tasks_test.dart @@ -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(find.byKey(const Key('chat-background-tasks-count'))) diff --git a/app/test/features/chat/conversation/chat_task_gear_test.dart b/app/test/features/chat/conversation/chat_task_gear_test.dart new file mode 100644 index 00000000..02ab70a2 --- /dev/null +++ b/app/test/features/chat/conversation/chat_task_gear_test.dart @@ -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(_rotationFinder); + +Badge _badge(WidgetTester tester) => tester.widget(_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.broadcast(); + List running = const []; + + @override + Stream get frames => _frames.stream; + + @override + Future 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 {}; + } + + 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)); + }); +} diff --git a/app/test/features/chat/conversation/chat_task_spinner_test.dart b/app/test/features/chat/conversation/chat_task_spinner_test.dart deleted file mode 100644 index 91c63978..00000000 --- a/app/test/features/chat/conversation/chat_task_spinner_test.dart +++ /dev/null @@ -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( - 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.broadcast(); - List running = const []; - - @override - Stream get frames => _frames.stream; - - @override - Future 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 {}; - } - - 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, - ); - }); -}