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

# 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

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

```html
<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

- [x] I have included a change request file using `$ npm run change`
- [x] 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.

## ⏭ 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

Author: janechu

change/@microsoft-fast-html-90d4b1e4-b272-4691-9b04-e6290ebc8b2f.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Add AttributeMap class for automatic @attr definitions on leaf template bindings",
+  "packageName": "@microsoft/fast-html",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/fast-html/DESIGN.md

@@ -89,6 +89,17 @@ An optional layer that uses the `Schema` to automatically:
 
 Enabled via `TemplateElement.options({ "my-element": { observerMap: "all" } })`.
 
+### `AttributeMap` — automatic `@attr` definitions
+
+An optional layer that uses the `Schema` to automatically register `@attr`-style reactive properties for every **leaf binding** in the template — i.e. simple expressions like `{{foo}}` or `id="{{foo-bar}}"` that have no nested properties, no explicit type, and no child element references.
+
+- The **attribute name** and **property name** are both the binding key exactly as written in the template (e.g. `{{foo-bar}}` → attribute `foo-bar`, property `foo-bar`). No normalization is applied.
+- Because HTML attributes are case-insensitive, binding keys should use lowercase names (optionally dash-separated).
+- Properties already decorated with `@attr` or `@observable` are left untouched.
+- `FASTElementDefinition.attributeLookup` and `propertyLookup` are patched so `attributeChangedCallback` correctly delegates to the new `AttributeDefinition`.
+
+Enabled via `TemplateElement.options({ "my-element": { attributeMap: "all" } })`.
+
 ### Syntax constants (`syntax.ts`)
 
 All delimiters used by the parser are defined in a single `Syntax` interface and exported as named constants from `syntax.ts`. This makes the syntax pluggable and easy to audit.
@@ -284,6 +295,16 @@ flowchart LR
 
 For a deep dive into the schema structure, context tracking, and proxy system see [SCHEMA_OBSERVER_MAP.md](./SCHEMA_OBSERVER_MAP.md).
 
+### AttributeMap and leaf bindings
+
+When `attributeMap: "all"` is set, `AttributeMap.defineProperties()` is called after parsing. It iterates `Schema.getRootProperties()` and skips any property whose schema entry contains `properties`, `type`, or `anyOf` — keeping only plain leaf bindings. For each leaf:
+
+1. The schema key (e.g. `foo-bar`) is used as both the **attribute name** and the **JS property name** — no conversion is applied.
+2. A new `AttributeDefinition` is registered via `Observable.defineProperty`.
+3. `FASTElementDefinition.attributeLookup` and `propertyLookup` are updated so `attributeChangedCallback` can route attribute changes to the correct property.
+
+Because property names may contain dashes, they must be accessed via bracket notation (e.g. `element["foo-bar"]`).
+
 ---
 
 ## Lifecycle

packages/fast-html/README.md

@@ -217,6 +217,35 @@ if (process.env.NODE_ENV === 'development') {
 }
 ```
 
+#### `attributeMap`
+
+When `attributeMap: "all"` is configured for an element, `@microsoft/fast-html` automatically creates reactive `@attr` properties for every **leaf binding** in the template — simple expressions like `{{foo}}` or `id="{{foo-bar}}"` that have no nested properties.
+
+The **attribute name** and **property name** are both the binding key exactly as written in the template — no normalization is applied. Because HTML attributes are case-insensitive, binding keys should use lowercase names (optionally dash-separated). Properties with dashes must be accessed via bracket notation (e.g. `element["foo-bar"]`).
+
+Properties already decorated with `@attr` or `@observable` on the class are left untouched.
+
+```typescript
+TemplateElement.options({
+    "my-element": {
+        attributeMap: "all",
+    },
+}).define({ name: "f-template" });
+```
+
+With the template:
+
+```html
+<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 on the element prototype, enabling `setAttribute("first-name", "Jane")` to trigger a template re-render automatically.
+
 ### Syntax
 
 All bindings use a handlebars-like syntax.

packages/fast-html/src/components/attribute-map.spec.ts

@@ -0,0 +1,143 @@
+import { expect, test } from "@playwright/test";
+
+test.describe("AttributeMap", () => {
+    test.beforeEach(async ({ page }) => {
+        await page.goto("/fixtures/attribute-map/");
+        await page.waitForSelector("attribute-map-test-element");
+    });
+
+    test("should define @attr for a simple leaf property", async ({ page }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        const hasFooAccessor = await element.evaluate(node => {
+            const desc = Object.getOwnPropertyDescriptor(
+                Object.getPrototypeOf(node),
+                "foo",
+            );
+            return typeof desc?.get === "function";
+        });
+
+        expect(hasFooAccessor).toBeTruthy();
+    });
+
+    test("should define @attr for a dash-case property", async ({ page }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        const hasFooBarAccessor = await element.evaluate(node => {
+            const desc = Object.getOwnPropertyDescriptor(
+                Object.getPrototypeOf(node),
+                "foo-bar",
+            );
+            return typeof desc?.get === "function";
+        });
+
+        expect(hasFooBarAccessor).toBeTruthy();
+    });
+
+    test("should use binding key as-is for both attribute and property name", async ({
+        page,
+    }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        // Setting the foo-bar attribute should update the foo-bar property (no conversion)
+        await element.evaluate(node => node.setAttribute("foo-bar", "dash-case-test"));
+        const propValue = await element.evaluate(node => (node as any)["foo-bar"]);
+
+        expect(propValue).toBe("dash-case-test");
+    });
+
+    test("should not define @attr for event handler methods", async ({ page }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        // @click="{setFoo()}" etc. produce "event" type bindings — excluded from schema.
+        // Regular methods have a value descriptor, not a getter/setter.
+        const results = await element.evaluate(node => {
+            const proto = Object.getPrototypeOf(node);
+            const isAccessor = (name: string) => {
+                const desc = Object.getOwnPropertyDescriptor(proto, name);
+                return typeof desc?.get === "function";
+            };
+            return {
+                setFoo: isAccessor("setFoo"),
+                setFooBar: isAccessor("setFooBar"),
+                setMultiple: isAccessor("setMultiple"),
+            };
+        });
+
+        expect(results.setFoo).toBe(false);
+        expect(results.setFooBar).toBe(false);
+        expect(results.setMultiple).toBe(false);
+    });
+
+    test("should update template when attribute is set via setAttribute", async ({
+        page,
+    }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        await element.evaluate(node => node.setAttribute("foo", "attr-value"));
+
+        await expect(page.locator(".foo-value")).toHaveText("attr-value");
+    });
+
+    test("should update template when dash-case attribute is set via setAttribute", async ({
+        page,
+    }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        await element.evaluate(node => node.setAttribute("foo-bar", "bar-attr-value"));
+
+        await expect(page.locator(".foo-bar-value")).toHaveText("bar-attr-value");
+    });
+
+    test("should reflect property value back to attribute", async ({ page }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        await element.evaluate(node => {
+            (node as any).foo = "reflected";
+        });
+
+        // FAST reflects attributes asynchronously via Updates.enqueue
+        await page.evaluate(() => new Promise(r => requestAnimationFrame(r)));
+
+        const attrValue = await element.evaluate(node => node.getAttribute("foo"));
+        expect(attrValue).toBe("reflected");
+    });
+
+    test("should update definition attributeLookup for simple properties", async ({
+        page,
+    }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        // setAttribute triggers attributeChangedCallback via attributeLookup
+        await element.evaluate(node => node.setAttribute("foo", "lookup-test"));
+        const propValue = await element.evaluate(node => (node as any).foo);
+
+        expect(propValue).toBe("lookup-test");
+    });
+
+    test("should update definition attributeLookup for dash-case properties", async ({
+        page,
+    }) => {
+        const element = page.locator("attribute-map-test-element");
+
+        // setAttribute with foo-bar triggers attributeChangedCallback for the foo-bar property
+        await element.evaluate(node => node.setAttribute("foo-bar", "lookup-bar-test"));
+        const propValue = await element.evaluate(node => (node as any)["foo-bar"]);
+
+        expect(propValue).toBe("lookup-bar-test");
+    });
+
+    test("should not overwrite an existing @attr accessor", async ({ page }) => {
+        await page.waitForSelector("attribute-map-existing-attr-test-element");
+        const element = page.locator("attribute-map-existing-attr-test-element");
+
+        // The @attr default value must survive AttributeMap processing
+        const defaultValue = await element.evaluate(node => (node as any).foo);
+        expect(defaultValue).toBe("original");
+
+        // setAttribute must still work via the original @attr definition
+        await element.evaluate(node => node.setAttribute("foo", "updated"));
+        const updatedValue = await element.evaluate(node => (node as any).foo);
+        expect(updatedValue).toBe("updated");
+    });
+});

packages/fast-html/src/components/attribute-map.ts

@@ -0,0 +1,102 @@
+import type { FASTElementDefinition } from "@microsoft/fast-element";
+import { AttributeDefinition, Observable } from "@microsoft/fast-element";
+import type { Schema } from "./schema.js";
+
+/**
+ * AttributeMap provides functionality for detecting simple (leaf) properties in
+ * a generated JSON schema and defining them as @attr properties on a class prototype.
+ *
+ * A property is a candidate for @attr when its schema entry has no nested `properties`,
+ * no `type`, and no `anyOf` — i.e. it is a plain binding like {{foo}} or id="{{foo-bar}}".
+ *
+ * Attribute names are **not** normalized — the binding key as written in the template
+ * is used as both the attribute name and the property name. Because HTML attributes are
+ * case-insensitive, binding keys should be lowercase (optionally dash-separated).
+ * For example, {{foo-bar}} results in attribute `foo-bar` and property `foo-bar`.
+ */
+export class AttributeMap {
+    private schema: Schema;
+    private classPrototype: any;
+    private definition: FASTElementDefinition | undefined;
+
+    constructor(classPrototype: any, schema: Schema, definition?: FASTElementDefinition) {
+        this.classPrototype = classPrototype;
+        this.schema = schema;
+        this.definition = definition;
+    }
+
+    public defineProperties(): void {
+        const propertyNames = this.schema.getRootProperties();
+        const existingAccessorNames = new Set(
+            Observable.getAccessors(this.classPrototype).map(a => a.name),
+        );
+
+        for (const propertyName of propertyNames) {
+            const propertySchema = this.schema.getSchema(propertyName);
+
+            // Only create @attr for leaf properties:
+            // - no nested properties (not a dot-syntax path)
+            // - no type (not an explicitly typed value like an array)
+            // - no anyOf (not a child element reference)
+            if (
+                !propertySchema ||
+                propertySchema.properties ||
+                propertySchema.type ||
+                propertySchema.anyOf
+            ) {
+                continue;
+            }
+
+            // Skip if the property already has an accessor (from @attr or @observable)
+            if (existingAccessorNames.has(propertyName)) {
+                continue;
+            }
+
+            const attrDef = new AttributeDefinition(
+                this.classPrototype.constructor,
+                propertyName,
+                propertyName,
+            );
+
+            Observable.defineProperty(this.classPrototype, attrDef);
+
+            // Mutate the existing observedAttributes array on the class.
+            // FAST's FASTElementDefinition sets observedAttributes via
+            // Reflect.defineProperty with a concrete array value (non-configurable,
+            // non-writable), so the descriptor cannot be replaced. However, the
+            // array itself is mutable, and pushing into it works because
+            // registry.define() — which causes the browser to snapshot
+            // observedAttributes — is called AFTER this method runs.
+            const existingObservedAttrs: string[] | undefined = (
+                this.classPrototype.constructor as any
+            ).observedAttributes;
+            if (
+                Array.isArray(existingObservedAttrs) &&
+                !existingObservedAttrs.includes(propertyName)
+            ) {
+                existingObservedAttrs.push(propertyName);
+            }
+
+            if (this.definition) {
+                (this.definition.attributeLookup as Record<string, AttributeDefinition>)[
+                    propertyName
+                ] = attrDef;
+                (this.definition.propertyLookup as Record<string, AttributeDefinition>)[
+                    propertyName
+                ] = attrDef;
+
+                const attrs = (this.definition as any).attributes;
+                if (
+                    Array.isArray(attrs) &&
+                    !attrs.some(
+                        (existing: AttributeDefinition) =>
+                            existing.name === attrDef.name ||
+                            existing.attribute === attrDef.attribute,
+                    )
+                ) {
+                    attrs.push(attrDef);
+                }
+            }
+        }
+    }
+}

packages/fast-html/src/components/index.ts

@@ -1,9 +1,11 @@
+export { AttributeMap } from "./attribute-map.js";
 export { RenderableFASTElement } from "./element.js";
 export { ObserverMap } from "./observer-map.js";
 export {
-    ObserverMapOption,
-    TemplateElement,
+    AttributeMapOption,
     type ElementOptions,
     type ElementOptionsDictionary,
     type HydrationLifecycleCallbacks,
+    ObserverMapOption,
+    TemplateElement,
 } from "./template.js";