docs: add a guide to building form-associated elements#7655
Closed
AKnassa wants to merge 1 commit into
Closed
Conversation
The only page covering form association documented a mixin that no longer exists, so anyone following it hit a compile error. Adds a guide for the supported approach on a plain FASTElement, covering attachInternals, setFormValue, the name attribute, and the form lifecycle callbacks. Fixes microsoft#7198
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
Collaborator
|
The suggested documentation does not meet the quality expectations for our documentation site. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Adds a guide for building form-associated custom elements — inputs, checkboxes, selects — with FAST.
Why
There were no docs for this. Worse than none, actually: the only page in the repository that covered form association documented a
FormAssociatedmixin from@microsoft/fast-foundation, a package that no longer exists. So someone following the docs writesclass MyInput extends FormAssociated(FASTElement), gets a TypeScript error, and has nowhere to go.The docs were not merely silent — they were walking people into a wall.
What changed
One new page:
sites/website/src/docs/3.x/advanced/form-associated.md.It documents the approach that actually works today, which a maintainer had already endorsed on the issue: stay on a plain
FASTElement, setstatic formAssociated = true, callattachInternals(), and report your value withsetFormValue().It also covers the parts the four-line recipe leaves out, because each one is a real "why is my form empty?" trap:
nameattribute — without it your element contributes nothing toFormDataat allformResetCallback,formStateRestoreCallbackandformDisabledCallbackFormAssociatedmixin, so the old page stops misleading peopleHow to see it
Preview the docs site and open Advanced → Form-associated elements.
Every TypeScript sample on the page was compiled against the real built
fast-elementtype definitions under the repository's owntsconfigsettings, so the code in the guide is code that actually builds.Deliberately out of scope
The issue thread floats the idea of shipping generic form-associated base classes. That is an API design decision for maintainers, and folding it in here would turn a documentation PR into a design PR. Not touched.
Fixes #7198