feat: rework validation modes by mateusz-pietras · Pull Request #54 · leancodepl/leancode_forms

mateusz-pietras · 2026-08-13T10:08:13Z

No description provided.

One named mode on the form says what the form does: `disabled` (the default), `onUserInteraction`, or `onUnfocus`. It is broadcast to every field and subform, including ones registered or attached later, so a section added after the first submit behaves like one added at build time. The decision lives in one new file, `lib/src/validation_mode.dart`: the enum, the internal event enum, and `validatesOn` — a pure function of the event, the mode and the interaction flag. It reads no field status, which is what makes it safe on a pipeline that overwrites the status with `pending` and clears both error slots on every write. Above every mode: a field the user has never edited validates nothing on its own, and a subtree with `validationEnabled` off validates nothing at all. The switch is folded into the mode the form broadcasts, so a field has one input to obey rather than two, and a switched-off subtree is excluded from `validate()` and from every derived aggregate alike. `validate()` neither consults the mode nor changes it — escalation is deleted, which is what makes a single broadcast sufficient. Also: - `prefill(value)` writes a value the user did not type, without arming the guarantee. - `focusNode` and `focus()` move up to `AdvancedFieldController`, and `handleUnfocus()` runs the blur path — flushing a debounce in any mode, reusing a settled verdict, retrying a failed round, and reporting a throwing validator instead of leaking it into the zone. - A field or subform may claim its own mode and manage it from then on; a parent's later change reaches only the children that have not. - `validateWithAutovalidate()` is renamed `revalidateSync()`. - `SharedCall.invalidate()` drops a pass answered under settings that no longer hold. - The error report tag says `leancode_forms`, not the stale `advanced_forms`. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Cut the comment volume the validation-modes feature added, without changing behaviour: facts that were repeated across three to five doc-comments now live in one place and are linked from the rest. Rename three private members to stop them colliding with their neighbours: `_applyMode` -> `_publishValidationMode` (mirrors the form's peer), `_formEnabled` -> `_parentEnabled` (same concept as the form's field of that name), `_statusKeepingFailure` -> `_statusAfterAbort`. Add `AdvancedFieldController._validatesOn`, replacing three five-line `validatesOn(...)` calls, and inline the single-call-site `_flushDebounce` into `handleUnfocus`. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Both controllers interleaved several concerns in one file. Each concern now lives in its own part file of the same library, so private state stays reachable and no cross-file contract is needed. Field controller: focus handling and the async validation round machinery. Form controller: child wiring, relations and the state class. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

mateusz-pietras · 2026-08-14T21:19:33Z

+part of 'advanced_form_controller.dart';
+
+// Listeners on child fields and subforms, and what to update when they change.
+mixin _ChildWiring on ChangeNotifier {


Is it a good idea of extracting it here? I'm worried that the public API will be harder to lookup - wdyt?

As I said in the other comment, as long as it's mixin, not extension it's findable, then it's fine

Splitting this logic into few mixins was a very good idea. Much more readable when logic is grouped

KamilSztandur · 2026-08-16T12:40:31Z

        exception: error,
        stack: stack,
-        library: 'advanced_forms',
+        library: 'leancode_forms',


Why revert the name :D

KamilSztandur · 2026-08-16T12:42:27Z

-  FocusNode? _focusNode;
-
-  /// The [FocusNode] bound to this field, created on first use.
-  ///
-  /// Throws a [StateError] if controller is disposed.
-  FocusNode get focusNode {
-    if (isDisposed) {
-      throw StateError(
-        'Cannot use the focusNode of a disposed AdvancedTextFieldController.',
-      );
-    }
-
-    return _focusNode ??= FocusNode(
-      debugLabel:
-          'AdvancedTextFieldController${name?.isNotEmpty ?? false ? '($name)' : ''}',
-    );
-  }
-


I guess it's removed because AdvancedFieldController already provides it, but now I think that we should be able to pass our own focus node. Add it to constructor

KamilSztandur · 2026-08-16T12:43:35Z

    this.validationError,
    this.asyncError,
-    this.autovalidate = false,
+    this.mode = ValidationMode.disabled,


IIRC we wanted to change the name from disabled to manual

KamilSztandur · 2026-08-16T12:46:51Z

+// Runs async validation: starts a pass, waits for the result, and writes it
+// only if still current. Round tracking lives on the controller (`_currentRound`,
+// `_hasVerdict`, `_lastFailure`).
+extension _ValidationRounds<T, E extends Object>


Let's do it as mixin if possible, so it's explicitly declared where these methods are coming from when reading advanced_field_controller.dart code

KamilSztandur · 2026-08-16T12:53:17Z

+part of 'advanced_form_controller.dart';
+
+// Listeners on child fields and subforms, and what to update when they change.
+mixin _ChildWiring on ChangeNotifier {


As I said in the other comment, as long as it's mixin, not extension it's findable, then it's fine

KamilSztandur · 2026-08-16T12:53:46Z

+part of 'advanced_form_controller.dart';
+
+// Listeners on child fields and subforms, and what to update when they change.
+mixin _ChildWiring on ChangeNotifier {


Splitting this logic into few mixins was a very good idea. Much more readable when logic is grouped

KamilSztandur · 2026-08-16T12:55:13Z

@@ -0,0 +1,101 @@
+part of 'advanced_form_controller.dart';


I doesn't have to be part of this file

It's public API, just export it separately

KamilSztandur · 2026-08-16T12:57:27Z

  AdvancedFieldController({
    required T initialValue,
    Validator<T, E>? validator,
    AsyncValidation<T, E>? asyncValidation,
    this.name,
  })  : _value = AdvancedFieldState<T, E>(value: initialValue),


Oof I didn't notice it earlier. We have to allow developers to pass their own FocusNodes

PiotrRogulski · 2026-08-16T18:51:22Z

-  final bool autovalidate;
+  /// When this field validates itself. The **effective** mode: a field whose
+  /// form has validation switched off reports [ValidationMode.disabled].
+  final ValidationMode mode;


I'd name this field validationMode

PiotrRogulski · 2026-08-16T18:53:01Z

+  /// Not used for identity — fields are identified by reference.
+  String? get name;
+
+  /// Tells the field the user has left it.


the user has left it

IDK, but sounds weird to me

PiotrRogulski · 2026-08-16T18:54:39Z

+
+// Listeners on fields this form does not own — for external callbacks only.
+// Does not update the form's own state.
+mixin _Relations on ChangeNotifier {


Even though it's private, maybe we can tighten the on type to the controller type, instead of allowing any ChangeNotifier?

The similar thing goes for other mixins introduced in this PR

PiotrRogulski · 2026-08-16T18:58:11Z

+    unawaited(
+      validate().catchError((Object error, StackTrace stackTrace) {
+        _report(name, 'validating after focus loss', error, stackTrace);
+        return false;
+      }),
+    );


I'd override handleUnfocus as async and use regular await + try/catch

PiotrRogulski · 2026-08-16T19:01:27Z

+
+  void _setState(AdvancedFormState newValue);
+
+  final _onValuesChanged = ChangeNotifier();


Is this notifier (and _onStatusChanged) disposed of properly? 🤔

PiotrRogulski · 2026-08-16T19:03:16Z

Now at 1763 lines, tl;dr — split up into multiple files mayhaps?

mateusz-pietras force-pushed the feat/LMG-399-validation-modes branch from 037f412 to 6bcb4e7 Compare August 13, 2026 21:59

KamilSztandur force-pushed the fix/validation-issues branch from 0226b80 to 797f304 Compare August 14, 2026 07:43

mateusz-pietras force-pushed the fix/validation-issues branch from 797f304 to 21071e2 Compare August 14, 2026 10:23

mateusz-pietras changed the base branch from fix/validation-issues to refactor/forms-rework August 14, 2026 14:37

mateusz-pietras force-pushed the feat/LMG-399-validation-modes branch from 6bcb4e7 to d0d9e7f Compare August 14, 2026 14:41

mateusz-pietras and others added 2 commits August 14, 2026 17:07

docs: simplify docs

8963529

mateusz-pietras requested a review from KamilSztandur August 14, 2026 21:18

mateusz-pietras marked this pull request as ready for review August 14, 2026 21:18

mateusz-pietras commented Aug 14, 2026

View reviewed changes

KamilSztandur reviewed Aug 16, 2026

View reviewed changes

PiotrRogulski reviewed Aug 16, 2026

View reviewed changes


		void _setState(AdvancedFormState newValue);

		final _onValuesChanged = ChangeNotifier();

Uh oh!

Conversation

mateusz-pietras commented Aug 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants