[KamilSztandur]

Problem

The form decides when a field validates itself with one of three modes: on submit, on every keystroke, or when the field is left. Real forms keep asking for rules that are not on that list. The one that started this PR: an email field should stay quiet while it is typed for the first time, validate when the user leaves it, and from then on re-check every keystroke so the error disappears the moment the address is right. Today the only way to get that, or any other rule the package does not ship, is to switch modes by hand from listeners, which is fragile and easy to get wrong.

Solution

ValidationMode is now a class instead of an enum, and ValidationMode.custom(name, fn) makes a mode from your own rule. The four shipped modes are constants of the same class, written with the same two inputs your rule gets, so a custom mode is not a second-class citizen: set it on the form and it reaches every field and subform, set it on one field and that field keeps it.

// Re-check only when another field changes, never on this field's own edits.
final followsDependency = ValidationMode.custom(
  'followsDependency',
  (c) => c.event == ValidationEvent.dependencyChanged,
);

repeatPassword
  ..setValidationMode(followsDependency)
  ..subscribeToFields([password]);

The rule gets a ValidationContext with two fields: which event is happening (valueChanged, unfocus, dependencyChanged) and whether the user has ever left the field after editing it. That is all a rule needs, and all it gets.

The email case ships as a fourth built-in mode, ValidationMode.afterFirstUnfocus: like onUnfocus until the field is first left after an edit, like onUserInteraction from then on.

How it is nicer now

A rule you can say in one sentence is one function, with the package's guarantees still around it: an untouched field validates nothing whatever the rule says, validate() ignores the mode, a round runs sync before async, the mode reaches the whole tree. Nothing to switch by hand, nothing to keep in sync. The docs have a page for it, with examples and how to test a rule without a form.

Design decisions

• A rule never sees the status, the errors or the value. Every edit clears the errors and a debounced round sets the status to pending, so a rule that asked "is there an error" would stop validating at the exact moment the user started fixing the value. That is the trap the earlier five-mode design fell into, and the context is shaped so nobody can fall into it again.
• The untouched-field rule stays in the field, in front of every mode. It is enforced in one place, not left to whoever writes a rule.
• Modes are compared by name. Two custom modes with the same name are the same mode, so one built in build() is not a mode change and leaves a round in flight alone. A name must therefore be unique; a built-in name throws.
• ValidationMode.values is gone. With custom modes there is no finite list, so the getter would lie.
• The context is an object, not parameters, so a field can be added to it later without breaking every rule out there.
• afterFirstUnfocus flips to live only on an unfocus. validate() from a submit button does not count, reset() flips it back, and leaving a field the user never edited does not count.

Breaking changes

For an app that uses only the shipped modes: an exhaustive switch over ValidationMode needs a default case, and ValidationMode.values no longer exists. Everything else compiles unchanged. This is a 0.3.0.

Demo

The "Try it" island on the Validation modes page, in afterFirstUnfocus: two letters typed with no error, the error appears on leaving the field, a third letter clears it at once, backspace brings it back at once.

Where it shows

The package: ValidationMode, ValidationContext and ValidationEvent in validation_mode.dart, one bit in the field controller. Docs: a new page "Your own validation mode", the mode table and gate table on the modes page, README section, FAQ, internals, the skill and its validation reference, the mode-switching demo. Tests cover the custom modes (what they see, that they cannot reach an untouched field, equality by name, broadcast to subforms) and both halves of afterFirstUnfocus.

🤖 Generated with Claude Code

[github-actions]

Docs preview: https://advanced-forms-k85euu9u2-leancode.vercel.app

Built from 4caeb4a; the landing page is at /, the docs under /docs.

[KamilSztandur]

@mhnowak Here it is :)

[Albert221]

IMO instead of introducing yet another enum value for the validation mode, the ValidationMode could become a strategy, that given all of the state we have about a given field and the surrounding form can form a decision whether the field should be validated. And that would mean that all custom behaviors our users might want to have for their forms are possible to implement as first-class citizens of the package. Following open-closed principle

[PiotrRogulski]

I'm not a fan of such a solution. I'd implement different strategies as subclasses (and a custom strategy would be, e.g., extends CustomValidationMode). Then, to detect a change in the mode, you just compare types

[KamilSztandur]

It wouldn't be able to tell difference between different custom modes, if we only compare by types, I think. Comparing by == instead means every custom mode writes its own equality (so it's easy to make a bug for devs using it).

I believe a name is the smallest explicit identity. Let me know if you disagree and have strong opinion on it

[PiotrRogulski]

We would be able — we would have two different types

[PiotrRogulski]

I feel like relying on runtime checks for forbidden names might be super inconvenient. With types, no such restriction would exist

[mateusz-pietras]

Yeah, +1 on strategy pattern, I think it fits here perfectly.

[PiotrRogulski]

Maybe I'm missing the point of this document, but I still don't see a reason to mention "bringing anything back", especially when singling out one validation mode 🤔