Improve WatchingStatefulWidget example with better local state pattern

- Replaced SearchableList with NotificationToggle
- Shows true local UI state (_isAnimating) for immediate feedback
- Demonstrates updating manager (toggleNotifications) from local interaction
- Better illustrates when StatefulWidget is actually needed
- Local state for UI, reactive state for business logic from manager

Author: escamoteur

code_samples/lib/watch_it/watching_widgets_patterns.dart

@@ -16,49 +16,49 @@ class TodoList extends WatchingWidget {
 }
 // #endregion watching_widget_basic
 
-// Helper class for searchable examples
-class Item {
-  final String name;
-  Item(this.name);
-}
+// Helper class for settings example
+class SettingsManager {
+  final notificationsEnabled = ValueNotifier<bool>(true);
+  final itemCount = ValueNotifier<int>(0);
 
-class Manager {
-  final items = ValueNotifier<List<Item>>([
-    Item('Apple'),
-    Item('Banana'),
-    Item('Cherry'),
-  ]);
+  void toggleNotifications(bool enabled) {
+    notificationsEnabled.value = enabled;
+  }
 }
 
 // #region watching_stateful_widget
-class SearchableList extends WatchingStatefulWidget {
+class NotificationToggle extends WatchingStatefulWidget {
   @override
-  State createState() => _SearchableListState();
+  State createState() => _NotificationToggleState();
 }
 
-class _SearchableListState extends State<SearchableList> {
-  String _query = ''; // Local state
+class _NotificationToggleState extends State<NotificationToggle> {
+  bool _isAnimating = false; // Local UI state for animation
 
   @override
   Widget build(BuildContext context) {
-    // Reactive state - automatically rebuilds
-    final items = watchValue((Manager m) => m.items);
-
-    // Filter using local state
-    final filtered = items.where((item) => item.name.contains(_query)).toList();
-
-    return Column(
-      children: [
-        TextField(
-          onChanged: (value) => setState(() => _query = value),
-        ),
-        Expanded(
-          child: ListView.builder(
-            itemCount: filtered.length,
-            itemBuilder: (context, index) => Text(filtered[index].name),
-          ),
-        ),
-      ],
+    // Reactive state - automatically rebuilds when manager changes
+    final enabled = watchValue((SettingsManager m) => m.notificationsEnabled);
+
+    return SwitchListTile(
+      title: Text('Notifications'),
+      subtitle: _isAnimating ? Text('Updating...') : null,
+      value: enabled,
+      onChanged: (value) async {
+        // Update local state for immediate UI feedback
+        setState(() => _isAnimating = true);
+
+        // Update manager (business logic)
+        di<SettingsManager>().toggleNotifications(value);
+
+        // Simulate async operation (API call, etc.)
+        await Future.delayed(Duration(milliseconds: 500));
+
+        // Clear local animation state
+        if (mounted) {
+          setState(() => _isAnimating = false);
+        }
+      },
     );
   }
 }
@@ -80,34 +80,34 @@ class TodoListWithMixin extends StatelessWidget with WatchItMixin {
 // #endregion mixin_stateless
 
 // #region mixin_stateful
-class SearchableListWithMixin extends StatefulWidget
+class NotificationToggleWithMixin extends StatefulWidget
     with WatchItStatefulWidgetMixin {
-  const SearchableListWithMixin({super.key});
+  const NotificationToggleWithMixin({super.key});
 
   @override
-  State createState() => _SearchableListWithMixinState();
+  State createState() => _NotificationToggleWithMixinState();
 }
 
-class _SearchableListWithMixinState extends State<SearchableListWithMixin> {
-  String _query = '';
+class _NotificationToggleWithMixinState
+    extends State<NotificationToggleWithMixin> {
+  bool _isAnimating = false;
 
   @override
   Widget build(BuildContext context) {
-    final items = watchValue((Manager m) => m.items);
-    final filtered = items.where((item) => item.name.contains(_query)).toList();
-
-    return Column(
-      children: [
-        TextField(
-          onChanged: (value) => setState(() => _query = value),
-        ),
-        Expanded(
-          child: ListView.builder(
-            itemCount: filtered.length,
-            itemBuilder: (context, index) => Text(filtered[index].name),
-          ),
-        ),
-      ],
+    final enabled = watchValue((SettingsManager m) => m.notificationsEnabled);
+
+    return SwitchListTile(
+      title: Text('Notifications'),
+      subtitle: _isAnimating ? Text('Updating...') : null,
+      value: enabled,
+      onChanged: (value) async {
+        setState(() => _isAnimating = true);
+        di<SettingsManager>().toggleNotifications(value);
+        await Future.delayed(Duration(milliseconds: 500));
+        if (mounted) {
+          setState(() => _isAnimating = false);
+        }
+      },
     );
   }
 }

docs/documentation/watch_it/watching_widgets.md

@@ -29,12 +29,15 @@ Use when you need both `setState` AND reactive state:
 <<< @/../code_samples/lib/watch_it/watching_widgets_patterns.dart#watching_stateful_widget
 
 **Use this when:**
-- You need local UI state (search queries, form input, expansion state)
+- You need local UI state (form input state, animation flags, expansion state)
 - You need animation controllers
 - Mix `setState` with reactive updates
+- Local state triggers manager updates (like this switch example)
 
 **Note:** Your State class automatically gets all watch functions - no mixin needed!
 
+**Pattern:** Local state (`_isAnimating`) provides immediate UI feedback, while reactive state (`notificationsEnabled`) ensures the widget reflects manager changes from anywhere in the app.
+
 ## Alternative: Using Mixins
 
 If you have **existing widgets** you don't want to change, use mixins instead: