Remove the deprecated stream extension

CHANGELOG.md

@@ -9,6 +9,7 @@
   * The docs have a page for it with a live demo, and the README and the skill cover it too.
 * New built-in mode `ValidationMode.afterFirstUnfocus`: quiet while the user types, validates when the field is first left, and from then on validates every edit, so an error disappears the moment the value is fixed.
 * Breaking: an exhaustive `switch` over `ValidationMode` needs a default case, and `ValidationMode.values` is gone, because with custom modes there is no finite list.
+* Removed the deprecated `AdvancedFieldController.stream` extension, as announced; listen with `addListener`, `subscribeToFields` or the builder widgets, and wrap a listener in a `StreamController` where a pipeline needs a stream.
 
 ## 0.2.4
 

MIGRATION.md

@@ -49,7 +49,7 @@
 | `form.onValuesChangedStream` (`Stream<void>`) | `form.onValuesChanged` (`Listenable`) |
 | `form.onStatusChangedStream` (`Stream<FieldStatus>`) | `form.onStatusChanged` (`Listenable`, no payload) |
 | `BlocBuilder<FormGroupCubit, FormGroupState>` | `ValueListenableBuilder<AdvancedFormState>` — there is no `AdvancedFormBuilder` |
-| `FieldCubit.stream` (inherited from `Cubit`) | `AdvancedFieldController.stream` — deprecated extension, removed in 0.3.0 ([section 9](#9-migrating-a-custom-field)) |
+| `FieldCubit.stream` (inherited from `Cubit`) | none; a listener, or a stream you wrap around one ([section 9](#9-migrating-a-custom-field)) |
 | `Future<void> close()` | `void dispose()` |
 | `addDisposable(...)`, the `Disposable` mixin | **Removed** — override `dispose()` ([section 7](#7-lifecycle-close--dispose)) |
 
@@ -470,15 +470,39 @@ addRelation(
 
 Outside a form, a raw listener works the same way with the comparison written by hand and a `removeListener` in `dispose()`.
 
-**Code that composes streams** — rxdart operators, `await for`, merging fields into a pipeline. The deprecated `stream` extension bridges a field to a broadcast stream so helpers written against `FieldCubit.stream` keep compiling:
+**Code that composes streams** — rxdart operators, `await for`, merging fields into a pipeline. A field has no stream (the deprecated `stream` bridge was removed in 0.3.0). Where a pipeline needs one, own a small adapter next to the field and close it when the field goes:
 
 ```dart
-final subscription = quantityField.stream
+/// A field's states as a broadcast stream. Close it from dispose().
+class FieldStates<T, E extends Object> {
+  FieldStates(this._field) {
+    _controller = StreamController.broadcast(
+      onListen: () => _field.addListener(_emit),
+      onCancel: () => _field.removeListener(_emit),
+    );
+  }
+
+  final AdvancedFieldController<T, E> _field;
+  late final StreamController<AdvancedFieldState<T, E>> _controller;
+
+  void _emit() => _controller.add(_field.value);
+
+  Stream<AdvancedFieldState<T, E>> get stream => _controller.stream;
+
+  /// Ends every subscription and any `await for` over [stream].
+  Future<void> close() => _controller.close();
+}
+
+final quantities = FieldStates(quantityField);
+final subscription = quantities.stream
     .map((state) => state.value.amount)
     .listen(recalculateTotals);
+
+// In dispose(), before the field:
+await quantities.close();
 ```
 
-Three caveats: every read allocates a new `StreamController`, so store it rather than re-reading the getter; the controller is never closed, so unlike `Cubit.stream` it does not terminate an `await for` loop; and it goes away in 0.3.0.
+`close()` is what `Cubit.close()` used to do for you: it completes the stream, so an `await for` loop ends and listeners are detached.
 
 ---
 

docs/faq.mdx

@@ -175,9 +175,9 @@ needs a fresh controller. Consider `setValidationEnabled(false)` instead of deta
 <Accordion title="Where did the streams go?">
 
 0.1.x controllers were cubits, so they had a `stream`. 0.2 is `Listenable`-based: `addListener`,
-`subscribeToFields`, `onValuesChanged`, `onStatusChanged`, and the builder widgets. A deprecated
-`AdvancedFieldController.stream` extension exists as a migration bridge and is removed in 0.3.0. See
-[Migration](./migration.mdx).
+`subscribeToFields`, `onValuesChanged`, `onStatusChanged`, and the builder widgets. The deprecated
+`AdvancedFieldController.stream` bridge was removed in 0.3.0; a pipeline that needs a stream wraps a listener in a
+`StreamController` (the recipe is in the repo's `MIGRATION.md`, section 9). See [Migration](./migration.mdx).
 
 </Accordion>
 </Accordions>

docs/migration.mdx

@@ -93,7 +93,7 @@ until the user edits it; where it must, call `validate()` on it from a listener
 | `removeSubform(form, close: …)` | `removeSubform(form)` — detaches only, returns `void` |
 | `Future<void> close()`, `addDisposable`, `Disposable` | `void dispose()` |
 | `BlocBuilder<FormGroupCubit, FormGroupState>` | `ValueListenableBuilder<AdvancedFormState>` |
-| `FieldCubit.stream` | `AdvancedFieldController.stream` — deprecated bridge, removed in 0.3.0 |
+| `FieldCubit.stream` | none; a listener, or a stream you wrap around one (see the repo's `MIGRATION.md`, section 9) |
 
 ## Behaviour changes that are not renames
 

lib/advanced_forms.dart

@@ -6,7 +6,6 @@ library;
 
 export 'src/field/advanced_boolean_field_controller.dart';
 export 'src/field/advanced_field_controller.dart';
-export 'src/field/advanced_field_controller_extensions.dart';
 export 'src/field/advanced_field_state.dart';
 export 'src/field/advanced_multi_select_field_controller.dart';
 export 'src/field/advanced_single_select_field_controller.dart';