Skip to content

docs: add a guide to building form-associated elements#7655

Closed
AKnassa wants to merge 1 commit into
microsoft:mainfrom
AKnassa:docs/7198-form-associated
Closed

docs: add a guide to building form-associated elements#7655
AKnassa wants to merge 1 commit into
microsoft:mainfrom
AKnassa:docs/7198-form-associated

Conversation

@AKnassa

@AKnassa AKnassa commented Jul 13, 2026

Copy link
Copy Markdown

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 FormAssociated mixin from @microsoft/fast-foundation, a package that no longer exists. So someone following the docs writes class 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

00-control-stale-guide-frontmatter 01-sidebar-new-entry 02-sidebar-advanced-closeup 03-content-code-samples 04-console-clean

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, set static formAssociated = true, call attachInternals(), and report your value with setFormValue().

It also covers the parts the four-line recipe leaves out, because each one is a real "why is my form empty?" trap:

  • the name attribute — without it your element contributes nothing to FormData at all
  • formResetCallback, formStateRestoreCallback and formDisabledCallback
  • validity and the built-in error message
  • a clear signpost that this replaces the removed FormAssociated mixin, so the old page stops misleading people

How 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-element type definitions under the repository's own tsconfig settings, 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

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

Copy link
Copy Markdown
Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

@AKnassa AKnassa marked this pull request as ready for review July 14, 2026 02:25
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

@radium-v

Copy link
Copy Markdown
Collaborator

The suggested documentation does not meet the quality expectations for our documentation site.

@radium-v radium-v closed this Jul 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add documentation on using the FormAssociated class

2 participants