feat(fast-html): add AttributeMap class for automatic @attr definitions

[janechu]

Pull Request

📖 Description

Adds an AttributeMap class to @microsoft/fast-html that automatically defines @attr properties on a custom element's class prototype based on the JSON schema generated by TemplateElement.

When attributeMap: "all" is configured for an element via TemplateElement.options(), AttributeMap inspects the schema after template processing and creates reactive properties for all leaf bindings — simple template expressions like {{foo}} or id="{{foo-bar}}" that have no nested properties, no array type, and no child element references.

Key behaviours:

• No normalization: the binding key as written in the template is used as-is for both the attribute name and the property name (e.g. {{foo-bar}} → attribute foo-bar, property foo-bar)
• Lowercase required: because HTML attributes are case-insensitive, binding keys should use lowercase names (optionally dash-separated)
• Bracket notation: properties containing dashes must be accessed via bracket notation (e.g. element["foo-bar"])
• Skips non-leaf properties: paths like {{user.name}} result in user having sub-properties in the schema and are excluded
• Skips existing accessors: properties already decorated with @attr or @observable are left untouched
• Updates FASTElementDefinition: attributeLookup and propertyLookup are patched so attributeChangedCallback correctly delegates to the new AttributeDefinition
• No decorator syntax required: uses Observable.defineProperty with an AttributeDefinition instance directly

Usage

TemplateElement.options({
    "my-element": {
        attributeMap: "all",
    },
});

<f-template name="my-element">
    <template>
        <p>{{greeting}}</p>
        <p>{{first-name}}</p>
    </template>
</f-template>

This registers greeting (attribute greeting, property greeting) and first-name (attribute first-name, property first-name) as @attr properties, enabling setAttribute("first-name", "Jane") to trigger a template re-render automatically.

This mirrors the existing ObserverMap integration pattern.

📑 Test Plan

Tests were added across two spec files:

• packages/fast-html/src/components/attribute-map.spec.ts — verifies accessor registration, no-normalization identity mapping, event handler exclusion, and FASTElementDefinition lookup updates
• packages/fast-html/test/fixtures/attribute-map/attribute-map.spec.ts — end-to-end tests verifying template re-rendering when properties are set via JavaScript or setAttribute

The attribute-map fixture follows the standard fixture pattern (entry.html, templates.html, state.json) and its index.html is generated by npm run build:fixtures with SSR-rendered shadow DOM.

All existing tests continue to pass.

✅ Checklist

General

• I have included a change request file using $ npm run change
• I have added tests for my changes.
• I have tested my changes.
• I have updated the project documentation to reflect my changes.
• I have read the CONTRIBUTING documentation and followed the standards for this project.

⏭ Next Steps

• Investigate whether observedAttributes can be updated after element registration to fully support the DOM attribute → property direction for elements registered before the template is processed

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds an AttributeMap feature to @microsoft/fast-html to automatically define @attr-style reactive properties for leaf template bindings, enabled via TemplateElement.options({ ..., attributeMap: "all" }).

Changes:

• Introduces AttributeMap + attributeMap element option and wires it into TemplateElement processing.
• Adds a new fixture and Playwright coverage validating attribute/property identity mapping and re-render behavior via setAttribute.
• Updates package docs and fixture build script to document and include the new capability.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/fast-html/src/components/template.ts	Adds attributeMap option plumbing and invokes AttributeMap.defineProperties() during template processing.
packages/fast-html/src/components/index.ts	Exports AttributeMap and AttributeMapOption from the public components entrypoint.
packages/fast-html/src/components/attribute-map.ts	Implements schema-driven detection of leaf bindings and defines them as @attr accessors.
packages/fast-html/src/components/attribute-map.spec.ts	Adds Playwright tests validating generated accessors, exclusions, reflection, and lookup patch behavior.
packages/fast-html/scripts/build-fixtures.js	Registers the new attribute-map fixture in the fixture build list.
packages/fast-html/test/fixtures/attribute-map/entry.html	Adds the fixture entry page for E2E tests.
packages/fast-html/test/fixtures/attribute-map/index.html	Adds the generated SSR fixture output HTML for the new fixture.
packages/fast-html/test/fixtures/attribute-map/main.ts	Defines test custom elements and configures TemplateElement.options({ attributeMap: "all" }).
packages/fast-html/test/fixtures/attribute-map/state.json	Initial fixture state for leaf bindings (foo, foo-bar).
packages/fast-html/test/fixtures/attribute-map/templates.html	Fixture templates exercising leaf bindings and click handlers.
packages/fast-html/test/fixtures/attribute-map/attribute-map.spec.ts	Adds fixture-based Playwright E2E tests (DOM behavior + reflection).
packages/fast-html/README.md	Documents the new attributeMap option, behavior, and usage.
packages/fast-html/DESIGN.md	Adds design/behavior notes explaining AttributeMap and “leaf binding” rules.
change/@microsoft-fast-html-90d4b1e4-b272-4691-9b04-e6290ebc8b2f.json	Adds the change file for release notes/versioning.