feat: granular field composables

[logaretm]

What

This PR breaks up the field composables into smaller, more granular composables for use in UI libraries that follow the field and control pattern.

How

A form-field can be defined as:

• A control that the user interacts with.
• A group of labels/descriptions, and error messages.

This PR models this relationship by breaking a field composable into:

• use___Control: Handles all the logic related to the control (e.g: Interactions and props).
• useFormField: Handles the state and labeling/descriptions/error message relationships with the control.

Usage

There are a couple of configurations to put all three composables together. A same-component approach and injectable approach.

Let's take a look at a TextField implementation.

Same component approach

Similar to how Formwerk will expose the full field composables, where all three are composed in the same composable. In this case, the labeling is colocated with the control.

// TextField.vue
// Build the state
 const field = useFormField<string | undefined>({
  label: props.label,
  description: props.description,
  path: props.name,
  initialValue: toValue(props.modelValue) ?? toValue(props.value),
  disabled: props.disabled,
  schema: props.schema,
});

// Build the control
const { inputEl, inputProps } = useTextControl(props, { field });

Injection Approach

This suits UI libraries more as they usually maintain their separate FormField component.

At a FormField component implementation:

// FormField.vue
const field = useFormField<string | undefined>({
  label: props.label,
  description: props.description,
  path: props.name,
  initialValue: toValue(props.modelValue) ?? toValue(props.value),
  disabled: props.disabled,
  schema: props.schema,
});

Then, at the control level, like an <Input > component, you only need to call the useTextControl composable:

// Input.vue
const { inputEl, inputProps } = useTextControl(props);

Under the hood the control composable will find the form field context and hook itself up.

Misc

supports genu/ui#1

[changeset-bot]

🦋 Changeset detected

Latest commit: 58cfafe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@formwerk/core	Minor
@formwerk/devtools	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/formwerkjs/formwerk/@formwerk/core@205

npm i https://pkg.pr.new/formwerkjs/formwerk/@formwerk/devtools@205

commit: 57c8b75

[genu]

@logaretm Say in the Injectable Approach we want to use some value from the state.

Would we use useFieldStateInjection() alongside useTextControl?

So, we would do something like this?

const { errorMessage } = useFieldStateInjection()!
const { inputEl, inputProps } = useTextControl({  name })

[logaretm]

const { errorMessage } = useFieldStateInjection()!
const { inputEl, inputProps } = useTextControl({  name })

You can do that if you want to, as useFieldStateInjection doesn't create the state object it just injects it. Is there a limitation you are trying to bypass?

[logaretm]

@genu Thinking about combining the useFieldState and useFormField because its too confusing to have two required pieces detached like that. What do you think?

EDIT: I just pushed this, feels much cleaner and will make migrating other fields easier.

[genu]

@genu Thinking about combining the useFieldState and useFormField because its too confusing to have two required pieces detached like that. What do you think?

EDIT: I just pushed this, feels much cleaner and will make migrating other fields easier.

Just pulled the latest. It definitely feels more elegant 🚀

[genu]

@logaretm Should we export the inputId from use__Control.ts or useFormField() or both? This can be useful when adding extra elements with ids.

For example, in NuxtUi, a FormField has a hint and a help. Currently, I'm doing this:

const { labelProps  } = useFormField(...)

<span :id="`${labelProps?.id}-hint`">...</span>

<div :id="`${labelProps?.id}-help`">...</div>      

[genu]

@logaretm Do we need to expose _field to the user?

I'm thinking that it can be confusing as most of the _field properties are already exposed.

Would there be any benefit to be able to extract a property from both?

const { isTouched, _field } = useTextField({ label: 'label' })

const v1 = isTouched.value
const v2 = _field.isTouched.value

[genu]

@logaretm Should there be distinction between useFormField, use__Control, and use__Field when we expose properties?

For example, at the moment, we can do:

const { inputEl, inputProps, labelProps } = useTextControl(...)

but a Text control, technically, wouldn't ever have a label, as it would be a lower level control.

[genu]

I believe we talked about exposing controlEl here.