FormControl base component RFC

[dkacper]

PoC: #2865
Jira: https://vsf.atlassian.net/wiki/spaces/SFUI/pages/177537032/FormControl+component

Background

Building form fields is not trivial. In most cases you'd like to add more than just an input. You need a label, an error message, and sometimes some text describing the field a bit better for a user. We want to introduce a new base component that would help to build this kind of a complex fields in a convenient way, and follow all required a11y rules at the same time.

Proposal

FormControl could be a base component. Because we want to provide high flexibility we could implement it using context API in React and Provide/Inject API in Vue. <FormControl> would be only a context provider, so we would have to implement a bunch of related components:

1. FormControl – context provider.
2. FormLabel – to set associated input id with a label and visually reflect states like disabled.
3. FormError – already styled error message that would display only when the field is invalid.
4. FormHelperText – the only reason I can see to keep it in that list is the fact that the input should point to its text via aria-describedby attribute.

What should be the context interface?

{
  id: string
  invalid: boolean
  disabled: boolean
  readOnly: boolean
}

All of these values user should be able to pass via <FormControl> props. However, we should provide default values for all of them. Booleans could be false by default, and the id could be automatically generated. It could be a nice feature when user don't have to bother setting the id manually.

Other consumers

Field components must loosely consume the context values. It means they should work within <FormControl> and without it. We could expose useFormControl hook/composable, to easily get the context or inject all the values.

Components that should inject form control values (consume the context):

1. Checkbox
2. Input
3. Radio
4. Select
5. Switch
6. RatingButton

a11y rules we should follow

1. Every input (field in general) should have a corresponding label. Input's id must be passed to the label using HTML for attribute.
2. All text related to an input must point to it by aria-describedby attribute on the input. Error message and helper text must generate their own IDs and pass them if displayed.
3. If input is invalid (means error message is displayed) we must pass aria-invalid attribute the the input.

Usage example

Vue

<SfFormControl :invalid="isInvalid">
  <SfFormLabel>Label</SfFormLabel>
  <SfInput v-model="modelValue" />
  <SfFormError>Error message</SfFormError>
  <SfFormHelperText>Helper text</SfFormError>
</SfFormControl>

React

<SfFormControl invalid={isInvalid}>
  <SfFormLabel>Label</SfFormLabel>
  <SfInput value={value} onChange={onChange} />
  <SfFormError>Error message</SfFormError>
  <SfFormHelperText>Helper text</SfFormHelperText>
</SfFormControl>

Open questions

There were some open question before that I want to address now.

Do we want to use this kind of FormControl component within all of our blocks?

It depends. I'd say in some block, yes, but not in each and everyone. Definitely, base components like <SfInput> or <Radio> that are going to consume the context must showcase how they could be combined with the FormControl. However, in blocks like forms we should focus on delivering the actual value, so fulfilling the use case. In my opinion using FormControl may bring unwanted noise in this kind of blocks.

What should be the scope of FormControl component? Should we implement subcomponents like Label, ErrorMessage? How should they be styled?

I can see high benefit of having these as base components. I think we should also style them, so they follow SFUI design guidelines. We could also extract hook/composable to consume the context, so the user may build their own label if needed.

What should take priority - props on the input component level or state coming from FormControl component?

I think it's clear that props on the component should take priority over the values coming from the context. FormControl provides high-level context, but if any of the components would have to by any reason override the values, they should take priority.

Should the error state be automatically passed to the input components?

Yes, I think that's one of the biggest benefits – shared state, automatically synced between all subcomponents.

[dkacper]

We'd like to close this RFC by July 6. If you want to suggest any changes, make sure to do it until that date.

[FRSgit]

Every input (field in general) should have a corresponding label. Input's id must be passed to the label using HTML for attribute.

True, label is required, but FormLabel element is not - label might be provided as aria-label on input element level

[dkacper]

Yes, <FormLabel> component is optional, you don't have to use it. I just wanted to emphasise that ID must be a part of the context and <FormLabel> must use it automatically.

[FRSgit]

Okay, I understand it now - I would reword it like:

Every input (field in general) should have a corresponding label **(either provided using `label` element or via `aria-label` attribute).

[FRSgit]

I would add a additional sentence here:

All text related to an input must be referenced using aria-describedby attribute on the input. Multiple values might be specified on aria-describedby using ID reference list. Error message and helper text must generate their own IDs and pass them if displayed.

[FRSgit]

Do we want to use this kind of FormControl component within all of our blocks?

I agree with response provided by you - we should showcase how to use different components/block components in FormControl examples and reference these examples from other documentation pages

[FRSgit]

What should be the scope of FormControl component? Should we implement subcomponents like Label, ErrorMessage? How should they be styled?

I can see high benefit of having these as base components. I think we should also style them, so they follow SFUI design guidelines. We could also extract hook/composable to consume the context, so the user may build their own label if needed.

I think the composable is a must - composable that will allow user to consume (and change) the context values will make it easier to implement custom form field wrappers that use FormControl under the hood.

[dkacper]

This RFC has been approved and we're going to implement the FormControl base component.