Fix progress state not resetting between executions (v9.4.1)

- Add ProgressHandle.reset() to clear all state
- Wrap WithProgress factory functions to auto-reset before execution
- Update cancel() to also clear progress and statusMessage
- Add Command.resetProgress() for manual resets
- Fix tests to account for cancel() clearing progress/status

Fixes issue where canceled commands remained canceled on next run.

Author: escamoteur

CHANGELOG.md

@@ -1,3 +1,21 @@
+[9.4.1] - 2024-11-24
+
+### Bug Fixes
+
+- **Progress Control**: Fixed progress state not resetting between command executions
+  - Progress state (progress, statusMessage, isCanceled) now automatically resets at the start of each execution
+  - `cancel()` method now also clears progress and statusMessage (not just sets isCanceled flag)
+  - Prevents issues where canceled commands would remain canceled on subsequent runs
+  - Implementation uses wrapper functions in WithProgress factories to call `reset()` automatically
+
+**New Methods**:
+- `Command.resetProgress()` - Manually reset progress state (useful for clearing 100% progress from UI)
+
+**Technical Details**:
+- Added `ProgressHandle.reset()` method to clear all state back to initial values
+- All 8 WithProgress factory methods now wrap user functions to call `reset()` before execution
+- `cancel()` now sets isCanceled=true, progress=0.0, and statusMessage=null for clean UI state
+
 [9.4.0] - 2024-11-24
 
 ### New Features

lib/command_it.dart

@@ -619,6 +619,25 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
   /// The function must check `handle.isCanceled.value` and decide how to handle it.
   void cancel() => _handle?.cancel();
 
+  /// Manually resets all progress state to initial values.
+  ///
+  /// Clears progress (to 0.0), statusMessage (to null), and isCanceled (to false).
+  /// This is called automatically at the start of each execution, but can also
+  /// be called manually when needed (e.g., to clear 100% progress from UI after
+  /// completion).
+  ///
+  /// Example:
+  /// ```dart
+  /// // After successful completion, reset progress for next run
+  /// if (command.progress.value == 1.0) {
+  ///   await Future.delayed(Duration(seconds: 2));
+  ///   command.resetProgress();
+  /// }
+  /// ```
+  ///
+  /// For commands without progress (created with regular factories), this is a no-op.
+  void resetProgress() => _handle?.reset();
+
   /// optional hander that will get called on any exception that happens inside
   /// any Command of the app. Ideal for logging.
   /// the [name] of the Command that was responsible for the error is inside
@@ -1877,8 +1896,11 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
     // Create the ProgressHandle
     final handle = ProgressHandle();
 
-    // Wrap the user's function to inject the handle
-    Future<TResult> wrappedFunc(TParam param) => func(param, handle);
+    // Wrap the user's function to reset handle state and inject the handle
+    Future<TResult> wrappedFunc(TParam param) async {
+      handle.reset(); // Reset progress state before each execution
+      return await func(param, handle);
+    }
 
     // Create the command with the wrapped function
     final command = CommandAsync<TParam, TResult>(
@@ -1935,8 +1957,11 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
     // Create the ProgressHandle
     final handle = ProgressHandle();
 
-    // Wrap the user's function to inject the handle
-    Future<TResult> wrappedFunc() => func(handle);
+    // Wrap the user's function to reset handle state and inject the handle
+    Future<TResult> wrappedFunc() async {
+      handle.reset(); // Reset progress state before each execution
+      return await func(handle);
+    }
 
     // Create the command with the wrapped function
     final command = CommandAsync<void, TResult>(
@@ -1987,8 +2012,11 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
     // Create the ProgressHandle
     final handle = ProgressHandle();
 
-    // Wrap the user's action to inject the handle
-    Future<void> wrappedAction(TParam param) => action(param, handle);
+    // Wrap the user's action to reset handle state and inject the handle
+    Future<void> wrappedAction(TParam param) async {
+      handle.reset(); // Reset progress state before each execution
+      return await action(param, handle);
+    }
 
     // Create the command with the wrapped action
     final command = CommandAsync<TParam, void>(
@@ -2039,8 +2067,11 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
     // Create the ProgressHandle
     final handle = ProgressHandle();
 
-    // Wrap the user's action to inject the handle
-    Future<void> wrappedAction() => action(handle);
+    // Wrap the user's action to reset handle state and inject the handle
+    Future<void> wrappedAction() async {
+      handle.reset(); // Reset progress state before each execution
+      return await action(handle);
+    }
 
     // Create the command with the wrapped action
     final command = CommandAsync<void, void>(
@@ -2113,10 +2144,12 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
     // Create the ProgressHandle
     final handle = ProgressHandle();
 
-    // Wrap the user's function to inject the handle
+    // Wrap the user's function to reset handle state and inject the handle
     Future<TResult> wrappedFunc(
-            TParam param, UndoStack<TUndoState> undoStack) =>
-        func(param, handle, undoStack);
+        TParam param, UndoStack<TUndoState> undoStack) async {
+      handle.reset(); // Reset progress state before each execution
+      return await func(param, handle, undoStack);
+    }
 
     // Create the command with the wrapped function
     final command = UndoableCommand<TParam, TResult, TUndoState>(
@@ -2184,9 +2217,11 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
     // Create the ProgressHandle
     final handle = ProgressHandle();
 
-    // Wrap the user's function to inject the handle
-    Future<TResult> wrappedFunc(UndoStack<TUndoState> undoStack) =>
-        func(handle, undoStack);
+    // Wrap the user's function to reset handle state and inject the handle
+    Future<TResult> wrappedFunc(UndoStack<TUndoState> undoStack) async {
+      handle.reset(); // Reset progress state before each execution
+      return await func(handle, undoStack);
+    }
 
     // Create the command with the wrapped function
     final command = UndoableCommand<void, TResult, TUndoState>(
@@ -2248,9 +2283,12 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
     // Create the ProgressHandle
     final handle = ProgressHandle();
 
-    // Wrap the user's action to inject the handle
-    Future<void> wrappedAction(TParam param, UndoStack<TUndoState> undoStack) =>
-        action(param, handle, undoStack);
+    // Wrap the user's action to reset handle state and inject the handle
+    Future<void> wrappedAction(
+        TParam param, UndoStack<TUndoState> undoStack) async {
+      handle.reset(); // Reset progress state before each execution
+      return await action(param, handle, undoStack);
+    }
 
     // Create the command with the wrapped action
     final command = UndoableCommand<TParam, void, TUndoState>(
@@ -2313,9 +2351,11 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
     // Create the ProgressHandle
     final handle = ProgressHandle();
 
-    // Wrap the user's action to inject the handle
-    Future<void> wrappedAction(UndoStack<TUndoState> undoStack) =>
-        action(handle, undoStack);
+    // Wrap the user's action to reset handle state and inject the handle
+    Future<void> wrappedAction(UndoStack<TUndoState> undoStack) async {
+      handle.reset(); // Reset progress state before each execution
+      return await action(handle, undoStack);
+    }
 
     // Create the command with the wrapped action
     final command = UndoableCommand<void, void, TUndoState>(

lib/progress_handle.dart

@@ -77,13 +77,32 @@ class ProgressHandle {
 
   /// Requests cooperative cancellation of the operation.
   ///
-  /// Sets the [isCanceled] flag to true. The wrapped command function
-  /// is responsible for checking this flag and responding appropriately.
+  /// Sets the [isCanceled] flag to true and clears progress/status state.
+  /// The wrapped command function is responsible for checking this flag
+  /// and responding appropriately.
   ///
   /// This does NOT forcibly stop execution - cancellation is cooperative.
   /// The function must check `isCanceled.value` and decide how to handle it.
   void cancel() {
     _isCanceled.value = true;
+    _progress.value = 0.0;
+    _statusMessage.value = null;
+  }
+
+  /// Resets all progress state to initial values.
+  ///
+  /// Called automatically at the start of each command execution.
+  /// Resets:
+  /// - [progress] to 0.0
+  /// - [statusMessage] to null
+  /// - [isCanceled] to false
+  ///
+  /// This ensures each command execution starts with clean state,
+  /// especially important for the cancellation flag.
+  void reset() {
+    _progress.value = 0.0;
+    _statusMessage.value = null;
+    _isCanceled.value = false;
   }
 
   /// Disposes all internal notifiers.

pubspec.yaml

@@ -1,6 +1,6 @@
 name: command_it
 description: command_it is a way to manage your state based on `ValueListenable` and the `Command` design pattern. It is a rebranding of flutter_command.
-version: 9.4.0
+version: 9.4.1
 homepage: https://github.com/flutter-it/command_it
 
 screenshots:

test/progress_handle_test.dart

@@ -93,28 +93,75 @@ void main() {
       expect(statusCollector.values, ['Loading...', 'Processing...', null]);
     });
 
-    test('cancel sets isCanceled and notifies', () {
+    test('cancel sets isCanceled and clears progress/status', () {
+      // Set up some state first
+      handle.updateProgress(0.75);
+      handle.updateStatusMessage('Almost done');
+
+      expect(handle.progress.value, 0.75);
+      expect(handle.statusMessage.value, 'Almost done');
       expect(handle.isCanceled.value, false);
 
+      // Clear collectors to track cancel changes
+      progressCollector.clear();
+      statusCollector.clear();
+      canceledCollector.clear();
+
+      // Cancel
       handle.cancel();
+
+      // Verify all state was cleared
       expect(handle.isCanceled.value, true);
+      expect(handle.progress.value, 0.0);
+      expect(handle.statusMessage.value, null);
+
+      // Verify listeners were notified
       expect(canceledCollector.values, [true]);
+      expect(progressCollector.values, [0.0]);
+      expect(statusCollector.values, [null]);
+    });
 
-      // Calling cancel again is idempotent (value doesn't change, may not notify)
-      handle.cancel();
-      expect(handle.isCanceled.value, true);
-      // Listener may or may not fire again for same value - just verify it's canceled
+    test('reset clears all state back to initial values', () {
+      // Set up some state
+      handle.updateProgress(0.75);
+      handle.updateStatusMessage('Almost done');
+      handle.cancel(); // This sets isCanceled=true and clears progress/status
+
+      // Set progress again so reset() causes a change notification
+      handle.updateProgress(0.5);
+      handle.updateStatusMessage('Restarting...');
+
+      expect(handle.progress.value, 0.5);
+      expect(handle.statusMessage.value, 'Restarting...');
       expect(handle.isCanceled.value, true);
+
+      // Clear collectors to verify reset notifications
+      progressCollector.clear();
+      statusCollector.clear();
+      canceledCollector.clear();
+
+      // Reset
+      handle.reset();
+
+      // Verify all values reset to initial state
+      expect(handle.progress.value, 0.0);
+      expect(handle.statusMessage.value, null);
+      expect(handle.isCanceled.value, false);
+
+      // Verify listeners were notified of changes
+      expect(progressCollector.values, [0.0]);
+      expect(statusCollector.values, [null]);
+      expect(canceledCollector.values, [false]);
     });
 
     test('dispose cleans up all notifiers', () {
       handle.updateProgress(0.5);
       handle.updateStatusMessage('Test');
-      handle.cancel();
+      handle.cancel(); // cancel() also clears progress/status
 
       // Verify values were collected before dispose
-      expect(progressCollector.values, [0.5]);
-      expect(statusCollector.values, ['Test']);
+      expect(progressCollector.values, [0.5, 0.0]); // cancel() resets progress
+      expect(statusCollector.values, ['Test', null]); // cancel() resets status
       expect(canceledCollector.values, [true]);
 
       handle.dispose();
@@ -190,12 +237,56 @@ void main() {
         async.elapse(const Duration(milliseconds: 1000));
 
         expect(command.value, 'Canceled');
-        expect(command.progress.value, lessThan(1.0));
+        expect(command.progress.value, 0.0); // Cancel clears progress
+        expect(command.statusMessage.value, null); // Cancel clears status
+        expect(command.isCanceled.value, true);
 
         command.dispose();
       });
     });
 
+    test('progress state resets automatically on new run', () async {
+      int executionCount = 0;
+
+      final command = Command.createAsyncWithProgress<void, String>(
+        (_, handle) async {
+          executionCount++;
+          handle.updateProgress(0.5);
+          handle.updateStatusMessage('Running execution $executionCount');
+          await Future<void>.delayed(const Duration(milliseconds: 10));
+          return 'Execution $executionCount complete';
+        },
+        initialValue: '',
+      );
+
+      // First run
+      await command.runAsync();
+      expect(command.value, 'Execution 1 complete');
+      expect(command.progress.value, 0.5);
+      expect(command.statusMessage.value, 'Running execution 1');
+
+      // Second run - should automatically reset before execution
+      await command.runAsync();
+      expect(command.value, 'Execution 2 complete');
+      expect(command.progress.value, 0.5);
+      expect(command.statusMessage.value, 'Running execution 2');
+
+      // Cancel and verify state is cleared
+      command.cancel();
+      expect(command.progress.value, 0.0);
+      expect(command.statusMessage.value, null);
+      expect(command.isCanceled.value, true);
+
+      // Third run - should reset cancel flag and allow execution
+      await command.runAsync();
+      expect(command.value, 'Execution 3 complete');
+      expect(command.progress.value, 0.5);
+      expect(command.statusMessage.value, 'Running execution 3');
+      expect(command.isCanceled.value, false); // Reset on new run
+
+      command.dispose();
+    });
+
     test('default progress returns 0.0 for commands without handle', () {
       final command = Command.createAsync<void, String>(
         (_) async => 'Done',