🚀 Features
🛠️ Control Composables
formwerk/core now exposes use___Control composable variants of each field we shipped so far. For example: useTextField and useTextControl.
This allows for a more precise separation between the field and the control that are often needed in UI libraries that deal with forms, mainly to dry the common parts of a field like labels, descriptions, and error messages.
Previously you could only build this style of API:
<TextField v-model="value" label="My Field" />Now you can separate the text control from the field that would typically contain all the labels, errors and descriptions:
<FormField name="my-field">
<TextControl v-model="value" label="My Field" />
</FormField>This was requested a while back in #159 where designing such a component was not possible due to the requirement of a label being present. This should be possible now with this release.
Note that this is an addition, meaning all documented field composables are still present and are still recommended to be used in your own code.
This change also comes with significant changes to the types and their organization in the codebase, but no breaking changes were introduced there, if you encounter any problems or errors please let us know by creating a new issue.
🫳 Touched State Changes
This might be a breaking change for some, but the isTouched state behavior was changed to better match its description in the docs.
Old: a field was considered touched if it was blurred.
New: a field is considered touched if the user did interact with it, the exact definition depends on each field type.
A couple of examples:
- Date Fields: Considered touched when the user changes any of the date values or interacts with the associated calendar.
- OTP Fields: Considered touched when the user changes any of the code slot values.
That means while the touched state can overlap with dirty state, it doesn't depend on the current field value like dirty does.
For example if a user interacts with a field and changes its value, then it is both dirty and touched, but if they change the value back to the initial it will remain touched but won't be dirty anymore.
If you face any bugs or feel like any of the composables don't set their touched state as expected of this new definition then feel free to create an issue! We will continue to review these behaviors and tweak them as we reach a stable release.
💨 New Blurred State
We also released a isBlurred state across the forms and fields APIs, which behaves as you would expect. It is set only when a field emits a blur event, so it is more predictable than touched.
Thanks to @genu for this work!