[RRFC] FormAssociated mixins

[justinfagnani]

• I searched for an existing RRFC which might be relevant to my RRFC

Motivation

Building a form associated custom element requires a lot of common boilerplate:

• Setting static formAssociated = true
• Attaching ElementInternals
• Setting a default ARIA role
• Calling internals.setFormValue() when needed
• Representing the element's form value and the element state
• Exposing the value to the element's public API
• Handling formDisabledCallback()
• Handling formResetCallback() and formStateRestoreCallback()

Example

A simple-ish FormAssociated() element, with validation, might just forward an input's value to the element's value:

import {FormAssociated, value} from '@lit-labs/form';

class MyFormElement extends FormAssociated(LitElement, {
  role: 'textbox'
}) {

  @formValue()
  accessor value: string = '';
  
  @query()
  accessor #input: HTMLInputElement;

  render() {
    return html`<input .value=${this.value}> @input=${this.#onInput}`;
  }

  #onInput(e) {
    this.value = e.target.value;
  }

  protected _checkValidity() {
    if (this.value.length < 5) {
      return {
        flags: { tooLong: true },
        message: "value is too long",
        anchor: this.#input,
      };
    }
  }
}

In this case the FormAssociated mixin would:

• set static formAssociated = true
• set internals.role
• call setFormValue() when value changes
• Implements formStateRestoreCallback() to reset the value.

How

A FormAssociated() mixin, paired with @internals, @formValue and @formState decorators.

Current Behavior

Desired Behavior

References

• n/a

[justinfagnani]

There are a lot of possible variations on what a mixin might provide, especially in terms of the public API it creates on the element.

I think the the minimal end of the spectrum, like the sketch above, a mixin might add no new public API. It just helps the element author coordinate the form value, form associated callbacks, and form methods on ElementInternals.

Another point on the spectrum is to emulate many of the the methods of HTMLInputElement, like checkValidity(), validity, etc. HTMLInputElement is also very customizable in terms of validity constraints. I don't think most elements will want the element users to customize the constraints, but the element author may want to use a similar declarative API (min, max, pattern, etc) to define constraints, rather than have just a validity checking callback.

So we may want to start with a minimal-API-adding mixin, then layer a richer API mixin on top of that. The minimal-API mixin can optionally have support for pluggable constraints.

[maxpatiiuk]

I think the the minimal end of the spectrum, like the sketch above, a mixin might add no new public API. It just helps the element author coordinate the form value, form associated callbacks, and form methods on ElementInternals.

If that is the case, could FormAssociated be developed as a controller instead?
That would provide more flexibility and (marginally?) better performance.

[justinfagnani]

If that is the case, could FormAssociated be developed as a controller instead?

No, because it needs to override the form associated instance methods like formResetCallback().

[jpzwarte]

I love this. One thing though that should be considered & documented carefully is how to make such a custom form control accessible.

I'm not sure browsers are fully there yet for formAssociated controls.

[JamesIves]

Supportive of this. Working with forms is fairly confusing, so utilities like this are really helpful.

[caseywatts]

Here's a recent blog post that covers formAssociated pretty thoroughly!
https://frontendmasters.com/blog/form-associated-custom-elements-in-practice/