feat: add declarative map extensions#7491
Merged
janechu merged 6 commits intoreleases/fast-element-v3from Apr 24, 2026
Merged
Conversation
janechu
force-pushed
the
copilot/pr2-declarative-map-extensions
branch
3 times, most recently
from
6d29bb7 to
79a0f5a
Compare
5 tasks
janechu
force-pushed
the
copilot/pr2-declarative-map-extensions
branch
4 times, most recently
from
9130dde to
5972d45
Compare
janechu
changed the base branch from
copilot/pr1-core-template-resolver
to
releases/fast-element-v3
janechu
added a commit
that referenced
this pull request
Apr 24, 2026
# Pull Request ## 📖 Description Adds a new **Declarative HTML** documentation section to the 3.x docs site with four pages covering the full declarative template authoring workflow: - **Overview** — Purpose of declarative templates, when to use them, a hello world example, and comparison with imperative `html` tagged templates. - **Writing f-templates** — Template syntax including content/attribute/boolean/event bindings, directives (`f-when`, `f-repeat`, `f-ref`, `f-slotted`, `f-children`), dot-notation paths, execution context access (`$e`, `$c`), and expression limitations. - **Defining Elements** — `TemplateElement` registration, `templateOptions: "defer-and-hydrate"`, lifecycle callbacks (`config()`), element configuration (`options()`), `observerMap` and `attributeMap` usage. - **Server-Side Rendering** — The renderer-agnostic SSR contract, hydration flow, Declarative Shadow DOM output, state propagation, and `@microsoft/fast-build` CLI usage. Also adds cross-references from `packages/fast-element/README.md` and `DECLARATIVE_HTML.md` to the new docs. Based on the declarative template features from PRs #7490, #7491, #7492, and #7493. ## 📑 Test Plan - Website builds successfully with `npm run build -w sites/website` - All four pages render correctly in the 11ty output - `npm run checkchange` passes (no change files needed for docs-only changes to the website) ## ✅ Checklist ### General - [x] I have included a change request file using `$ npm run change` - [ ] I have added tests for my changes. - [x] I have tested my changes. - [x] I have updated the project documentation to reflect my changes. - [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.
Expose observerMap() and attributeMap() as FASTElement extensions and plumb definition-scoped declarative options through TemplateElement with the existing global options path kept as a temporary fallback. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove the explicit "all" map option so observerMap() and attributeMap() use the default behavior when no config object is passed, and update the declarative docs/examples to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Update the website's 3.x declarative API docs to reflect the removal of AttributeMapOption and ObserverMapOption and the new default map-option behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Fix the remaining declarative architecture examples that still referenced the removed explicit "all" map option. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
janechu
force-pushed
the
copilot/pr2-declarative-map-extensions
branch
from
5972d45 to
540ad04
Compare
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
1 participant
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.
Pull Request
📖 Description
This draft moves declarative map configuration onto
FASTElementDefinitionso declarative authoring can use normal FAST element extensions instead of the globalTemplateElement.options()setup.observerMap()andattributeMap()helpers on@microsoft/fast-element/declarative.jsTemplateElementconsume merged definition-scoped options while preservingTemplateElement.options()as a temporary fallback👩💻 Reviewer Notes
The key review points are the definition-scoped option plumbing in
definition-options.tsand the merge/fallback behavior inTemplateElement. This PR intentionally stops short of the laterdeclarativeTemplate()bridge.📑 Test Plan
npm run build:tsc -w @microsoft/fast-elementnpm run build:fixtures -w @microsoft/fast-elementnpm run doc -w @microsoft/fast-elementnpm run doc:exports -w @microsoft/fast-elementcd packages/fast-element && npx playwright test --config=playwright.declarative.config.ts --project=chromium test/declarative/fixtures/extensionsnpx @biomejs/biome check --colors=off packages/fast-element/src/declarative/attribute-map.ts packages/fast-element/src/declarative/definition-options.ts packages/fast-element/src/declarative/index.ts packages/fast-element/src/declarative/observer-map.ts packages/fast-element/src/declarative/template.ts packages/fast-element/test/declarative/fixtures/extensions/attribute-map-naming-strategy/main.ts packages/fast-element/test/declarative/fixtures/extensions/attribute-map/main.ts packages/fast-element/test/declarative/fixtures/extensions/observer-map-config-object/main.ts packages/fast-element/test/declarative/fixtures/extensions/observer-map-deep-merge/main.ts packages/fast-element/test/declarative/fixtures/extensions/observer-map-properties/main.ts packages/fast-element/test/declarative/fixtures/extensions/observer-map/main.tsnpm run checkchange -- --since 15b9fa630 --no-fetch✅ Checklist
General
$ npm run change⏭ Next Steps
A follow-up draft will teach
<f-template>/declarativeTemplate()to resolve templates through this definition-scoped configuration path.