✨ better behaviour for <FormState /> initialValue changes

[marutypes]

fixes #323 (hopefully, please let me know if this doesn't work for you)

What this?

As seen in the issue above, <FormState />'s behaviour around resetting could be problematic for some usecases. To address this I've added a new prop.

You can now control how <FormState /> reacts to changes in the initialValue prop using onInitialValueChanged. This prop has three options:

• (default) reset-all: Reset the entire form when initialValues changes.
• reset-where-changed: Reset only the changed field objects when initialValues changes.
• ignore: Ignore changes to the initialValues prop. This option makes <FormState /> behave like a fully controlled component. You will generally want to accompany this option with a key or ref.

In adding this I had to make some calls around whether to reset errors / dirty state, and I tried to do the right thing. Let me know if it's bad.

I also ended up moving formState#reset into the public namespace like validateForm so that it can be used with onInitialValueChanged: ignore if preferred to using a key.

Yeah but I want even more control

If there's a way we can make a simple api like this work for you I'd really rather do that. If it's really not doable, we can change this api to be

onInitialValueChanged: 
| 'reset-all'
| 'reset-changed'
| 'ignore'
| typeof FormState.getDerivedStateFromProps

In which case the user would be able to do literally anything they wanted. I had suggested something similar (but scoped to controlling how a given key of fields is reconciled) in the issue, but I'd rather avoid the 'cooking with flamethrowers' approach if we can.

Can I try?

Since the tophat script is still not merged and we don't have a playground yet, I made this sandbox:

https://codesandbox.io/s/z77yjjvwp

It might be a little out of date around prop names because I've changed them a thousand times, but it should give you an idea how this looks.

I think reset-where-changed should be the default

Same, but I want to do a relatively large 1.0+ bump sometime soon, so since that would be a pretty large breaking change lets see if that bears out and do it then :)

[marutypes]

this is probably the most asked question I get, so I snuck it in here since it's sorta on theme

[rexmac]

I'm thinking it would be helpful/safer to make these values constants or maybe an exported enum?

[marutypes]

For those with typescript supporting editors string unions autocomplete just as well either way, for those without they feel like a more naturalJS API. Personally for component apis I enjoy the convenience provided by string unions.

[rexmac]

For those with typescript supporting editors string unions autocomplete just as well either way

TIL

[marutypes]

:)

[rexmac]

LGTM. ❤️ the FAQ update!

[rox163]

🙏 lgtm!