Improve progress_control documentation and examples

- Update cancel() docs to explain it clears progress and statusMessage
- Add factory variants table for async commands with progress
- Fix Dio integration example to use try-finally pattern
- Remove CommandBuilder example (incompatible with watchValue)
- Remove subjective best practices
- Improve batch processing example to show per-item progress

Author: escamoteur

code_samples/lib/command_it/progress_batch_processing.dart

@@ -5,18 +5,26 @@ import '_shared/stubs.dart';
 final batchCommand = Command.createAsyncWithProgress<List<Item>, String>(
   (items, handle) async {
     final total = items.length;
-    int processed = 0;
+    int current = 0;
 
     for (final item in items) {
       if (handle.isCanceled.value) {
-        return 'Canceled ($processed/$total processed)';
+        return 'Canceled ($current/$total processed)';
       }
 
-      await processItem(item);
-      processed++;
+      current++;
+      handle.updateStatusMessage('Processing item $current of $total');
 
-      handle.updateProgress(processed / total);
-      handle.updateStatusMessage('Processed $processed of $total items');
+      // Process item with per-item progress
+      const steps = 10;
+      for (int step = 0; step <= steps; step++) {
+        if (handle.isCanceled.value) {
+          return 'Canceled ($current/$total processed)';
+        }
+
+        handle.updateProgress(step / steps);
+        await simulateDelay(50); // Simulate work step
+      }
     }
 
     return 'Processed $total items';

code_samples/lib/command_it/progress_dio_integration.dart

@@ -36,12 +36,18 @@ final downloadCommand = Command.createAsyncWithProgress<String, File>(
     final cancelToken = CancelToken();
 
     // Forward command cancellation to Dio
-    handle.isCanceled.listen((canceled, _) {
-      if (canceled) cancelToken.cancel('User canceled');
-    });
+    late final subscription;
+    subscription = handle.isCanceled.listen(
+      (canceled, _) {
+        if (canceled) {
+          cancelToken.cancel('User canceled');
+          subscription.cancel();
+        }
+      },
+    );
 
     try {
-      final response = await dio.download(
+      await dio.download(
         url,
         '/downloads/file.zip',
         cancelToken: cancelToken,
@@ -56,11 +62,8 @@ final downloadCommand = Command.createAsyncWithProgress<String, File>(
         },
       );
       return File('/downloads/file.zip');
-    } on DioException catch (e) {
-      if (CancelToken.isCancel(e)) {
-        return File(''); // Handle cancellation
-      }
-      rethrow;
+    } finally {
+      subscription.cancel();
     }
   },
   initialValue: File(''),

code_samples/lib/command_it/progress_factory_variants.dart

@@ -1,6 +1,23 @@
 import 'package:command_it/command_it.dart';
 import '_shared/stubs.dart';
 
+// #region main
+// Full signature: parameter + result
+final processCommand = Command.createAsyncWithProgress<int, String>(
+  (count, handle) async {
+    for (int i = 0; i < count; i++) {
+      if (handle.isCanceled.value) return 'Canceled';
+
+      await processItem(Item());
+      handle.updateProgress((i + 1) / count);
+      handle.updateStatusMessage('Processing item ${i + 1} of $count');
+    }
+    return 'Processed $count items';
+  },
+  initialValue: '',
+);
+// #endregion main
+
 // #region example
 // Full signature: parameter + result
 final processCommand = Command.createAsyncWithProgress<int, String>(

docs/documentation/command_it/progress_control.md

@@ -43,7 +43,16 @@ Use the `WithProgress` factory variants to create commands that receive a `Progr
 
 ### Async Commands with Progress
 
-<<< @/../code_samples/lib/command_it/progress_factory_variants.dart#example
+<<< @/../code_samples/lib/command_it/progress_factory_variants.dart#main
+
+All four async variants are available:
+
+| Factory Method | Function Signature |
+|---------------|-------------------|
+| `createAsyncWithProgress` | `(param, handle) async => TResult` |
+| `createAsyncNoParamWithProgress` | `(handle) async => TResult` |
+| `createAsyncNoResultWithProgress` | `(param, handle) async => void` |
+| `createAsyncNoParamNoResultWithProgress` | `(handle) async => void` |
 
 ### Undoable Commands with Progress
 
@@ -137,7 +146,13 @@ if (isCanceled) Text('Operation canceled')
 
 ### cancel()
 
-Request cooperative cancellation of the operation:
+Request cooperative cancellation of the operation. This method:
+
+- Sets `isCanceled` to `true`
+- Clears `progress` to `0.0`
+- Clears `statusMessage` to `null`
+
+This immediately clears progress state from the UI, providing instant visual feedback that the operation was canceled.
 
 ```dart
 // In UI:
@@ -185,7 +200,7 @@ if (command.progress.value == 1.0) {
 - Reset progress between manual executions
 - Prepare command state for testing
 
-**Note:** Progress is automatically reset at the start of each `run()` execution, so manual resets are typically only needed for UI cleanup or resuming operations.
+**Note:** Progress is automatically reset at the start of each `run()` execution, so manual resets are typically only needed for UI cleanup or resuming operations. Additionally, calling `cancel()` also clears progress and statusMessage to provide immediate visual feedback.
 
 ## Integration Patterns
 
@@ -209,33 +224,6 @@ The `isCanceled` property is a `ValueListenable`, allowing you to forward cancel
 
 <<< @/../code_samples/lib/command_it/progress_dio_integration.dart#example
 
-### With CommandBuilder
-
-CommandBuilder automatically exposes progress properties for easy UI integration:
-
-```dart
-CommandBuilder<File, String>(
-  command: uploadCommand,
-  whileRunning: (context, lastResult, param) {
-    final progress = uploadCommand.progress.value;
-    final status = uploadCommand.statusMessage.value;
-
-    return Column(
-      children: [
-        LinearProgressIndicator(value: progress),
-        SizedBox(height: 8),
-        Text(status ?? 'Processing...'),
-        TextButton(
-          onPressed: uploadCommand.cancel,
-          child: Text('Cancel'),
-        ),
-      ],
-    );
-  },
-  onData: (context, result, param) => Text('Result: $result'),
-)
-```
-
 ## Commands Without Progress
 
 Commands created with regular factories (without `WithProgress`) still have progress properties, but they return default values:
@@ -250,13 +238,16 @@ final command = Command.createAsync<void, String>(
 command.progress.value        // Always 0.0
 command.statusMessage.value   // Always null
 command.isCanceled.value      // Always false
-command.cancel()              // Does nothing
+command.cancel()              // No effect (no progress handle)
 ```
 
 This zero-overhead design means:
-- <ul style="list-style: none; padding-left: 0;"><li style="padding-left: 1.5em; text-indent: -1.5em;">✅ UI code can always access progress properties without null checks</li></ul>
-- <ul style="list-style: none; padding-left: 0;"><li style="padding-left: 1.5em; text-indent: -1.5em;">✅ No memory cost for commands that don't need progress</li></ul>
-- <ul style="list-style: none; padding-left: 0;"><li style="padding-left: 1.5em; text-indent: -1.5em;">✅ Easy to add progress to existing commands later (just change factory)</li></ul>
+
+<ul style="list-style: none; padding-left: 0;">
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ UI code can always access progress properties without null checks</li>
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ No memory cost for commands that don't need progress</li>
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ Easy to add progress to existing commands later (just change factory)</li>
+</ul>
 
 ## Testing with MockCommand
 
@@ -296,53 +287,6 @@ for (final item in items) {
 }
 ```
 
-### DO: Provide meaningful status messages
-
-```dart
-// ✅ Good - specific, actionable information
-handle.updateStatusMessage('Uploading file 3 of 10...');
-handle.updateStatusMessage('Processing image (1.2 MB)...');
-handle.updateStatusMessage('Verifying upload integrity...');
-```
-
-### DON'T: Use vague status messages
-
-```dart
-// ❌ Bad - not helpful to users
-handle.updateStatusMessage('Working...');
-handle.updateStatusMessage('Please wait...');
-```
-
-### DO: Update progress accurately
-
-```dart
-// ✅ Good - progress matches actual work done
-final total = items.length;
-for (int i = 0; i < total; i++) {
-  await processItem(items[i]);
-  handle.updateProgress((i + 1) / total);  // Accurate progress
-}
-```
-
-### DON'T: Set progress to 1.0 prematurely
-
-```dart
-// ❌ Bad - progress at 100% but still working
-handle.updateProgress(1.0);
-await finalizeOperation();  // Still working after "100%"
-```
-
-### DO: Clean up on cancellation
-
-```dart
-// ✅ Good - cleanup resources on cancel
-if (handle.isCanceled.value) {
-  await cleanupPartialUpload(uploadId);
-  await deleteTemporaryFiles();
-  return 'Canceled';
-}
-```
-
 ## Performance Considerations
 
 **Progress updates are lightweight** - each update is just a ValueNotifier assignment. However, avoid excessive updates: