docs: add documentation on using the FormAssociated class

[mvolkmann]

🙋 Documentation Request

As far as I can tell, the proper way to use the FormAssociated class in a FAST web component is to:

1. add import { FormAssociated } from "@microsoft/fast-foundation";
2. change extends FASTElement to extends FormAssociated(FASTElement)
3. add the property private internals: ElementInternals = this.elementInternals;
4. call this.internals.setFormValue(initialValue); in connectedCallback to set the initial value
5. call this.internals.setFormValue(newValue); every time the value changes

I tried all of this, but TypeScript doesn't like changes 2 and 3.

Where can I find an example of using the FormAssociated class or any documentation on it?

[davatron5000]

Agree @mvolkmann, we probably need better documentation here. To answer your question and give you an example in the interim, you might not need to extend FormAssociated...

On the Fluent side of things, we moved to extending FASTElement but setting static formAssociated = true on the form control elements. For example, our base BaseTextArea class:

https://github.com/microsoft/fluentui/blob/master/packages/web-components/src/textarea/textarea.base.ts

So that would update your instructions to:

1. Add static readonly formAssociated = true; to the class
2. Attach ElementInternals public internals: ElementInternals = this.attachInternals();
3. call this.internals.setFormValue(initialValue); in connectedCallback to set the initial value
4. call this.internals.setFormValue(newValue); every time the value changes

This should be all that's needed to get the custom element participating in forms.

Whether ElementInternals is public or private is up to you, we keep it public so we can access el.internals.role in our tests.

[chrisdholt]

Would welcome a PR here from anyone interested!

@mvolkmann the one thing I'll call out is that @microsoft/fast-foundation has been deprecated and IMO the FormAssociated mixin was fairly out of date and a bit monolithic. With that said, @davatron5000's on point with the above. There are also ways to create "generic" classes for things which are nearly functionally the same and are form associated as has been done with Checkbox/Radio/Option in Fluent UI. Each of these extend a base class which includes the relevant consistent functionality for form association.

[mvolkmann]

Thanks so much! The approach described by @davatron5000 worked perfectly for me.

The reason I asked the question is that I'm in the middle of writing a book on web components. It contains chapters on vanilla web components, Lit, Stencil, FAST, Solid, and wrec (my library). If anyone is interested in reviewing what I write about FAST, I'd be happy to share it before the book is published.