A conditional section in one line

[KamilSztandur]

Problem

A section that applies only sometimes, like invoice details behind an "I need an invoice" switch, takes a relation and two calls in every form:

addSubform(invoice);
addRelation(needsInvoice, (on) => on, (on) => on ? addSubform(invoice) : removeSubform(invoice));
if (!needsInvoice.fieldValue) removeSubform(invoice); // relations fire on change only

The seeding line is easy to forget, and the whole thing says nothing about what it is for. Piotr suggested that addSubform should just take the condition and do the attaching and detaching itself.

Solution

addSubform(invoice,  enabled: () => needsInvoice.fieldValue);
addSubform(shipping, enabled: () => !sameAsBilling.fieldValue);
addSubform(company,  enabled: () => type.fieldValue == CustomerType.company);

One optional parameter on a method everyone already uses. The form evaluates the closure when the section is added and again after every value change anywhere in its tree. While it is true the section is attached. When it turns false the section is detached, exactly as removeSubform would do: its fields leave validate(), canSubmit, getFieldValues() and allFields, so a payload built from the form has no invoice in it. The form owns the section either way, so its values stay in its fields and are back when the switch flips, and it is disposed with the form. A reset of the checkbox takes the section with it on its own. removeSubform drops the condition.

Cost: one closure call and a bool comparison per conditional section on each value change, next to the pass over all fields the form already does for wasModified.

Limit, written into the docs: a condition on something outside the form is not re-evaluated for that change. Attaching by hand still covers it.

In this PR

• enabled on addSubform, re-evaluated from the existing value-changed handler; attach and detach share the code with addSubform and removeSubform.
• Tests: detached but owned, attached at once when true, follows the fields it reads, values survive a detach, quiet when the result does not change, reacts to a change inside another subform, out of validate() while detached, parent mode reaches a late attach, resetAll() re-syncs, removeSubform drops the condition, re-attach and replace cases, outside field not followed.
• Example app: the wizard's invoice step uses it; the navigation follows the attached steps.
• Docs (subform patterns, subform index, wizard, relations table), SKILL.md and a changelog entry. The switch-validation-off pattern stays documented as the alternative for when resetAll and friends must keep reaching a hidden section.

flutter analyze clean in the package and the example, all 273 tests pass.

🤖 Generated with Claude Code

[github-actions]

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

Built from 1cf2ddf; the landing page is at /, the docs under /docs.

[mateusz-pietras]

IDK, as a user I think I would feel lost in this, when to use removeSubform, when to make it conditional... What about a separate method for that, leaving add/remove as an advanced feature, while idk attachSubform(form, condition) would stay a default way? I dont like either of these options tbh

[KamilSztandur]

@mateusz-pietras After reconsideration I agree that's API doubling, but I think it's in good faith.

Adding subform with "enabled by" hook, then removing it with "removeSubform" will simply deactivate that hook.

To make some order of this "chaos" I expanded Dart docs for this "enabledBy" parameter, explaining that it's convenient shortcut for most simple use cases

Let me know what you think:)

[mateusz-pietras]

LGTM