@microsoft/fast-element 2.10.4 → 3.0.0-rc.1

package/test/declarative/fixtures/extensions/observer-map-properties/main.ts

@@ -0,0 +1,175 @@
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { FASTElement } from "@microsoft/fast-element/fast-element.js";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
+
+class SelectiveObsElement extends FASTElement {
+    public user = {
+        name: "Alice",
+        age: 28,
+        history: {
+            joined: "2020-01-01",
+            visits: 100,
+        },
+        location: {
+            city: "New York",
+            country: "USA",
+        },
+    };
+
+    public settings = {
+        theme: "dark",
+        language: "en",
+    };
+
+    public analytics = {
+        charts: {
+            activeChart: "line",
+            cachedData: "heavy-data",
+        },
+        summary: "good",
+    };
+
+    public updateUserName = () => {
+        this.user.name = "Bob";
+    };
+
+    public updateUserAge = () => {
+        this.user.age = 29;
+    };
+
+    public updateHistory = () => {
+        this.user.history.visits = 200;
+    };
+
+    public updateLocation = () => {
+        this.user.location.city = "London";
+    };
+
+    public updateSettings = () => {
+        this.settings.theme = "light";
+    };
+
+    public updateActiveChart = () => {
+        this.analytics.charts.activeChart = "bar";
+    };
+
+    public updateCachedData = () => {
+        this.analytics.charts.cachedData = "updated-heavy-data";
+    };
+
+    public updateSummary = () => {
+        this.analytics.summary = "excellent";
+    };
+}
+
+SelectiveObsElement.define(
+    {
+        name: "selective-obs-element",
+        template: declarativeTemplate(),
+    },
+    [
+        observerMap({
+            properties: {
+                user: {
+                    name: true,
+                    age: true,
+                    history: false,
+                    location: true,
+                },
+                // settings is NOT listed → skipped
+                analytics: {
+                    charts: {
+                        $observe: false,
+                        activeChart: true,
+                    },
+                    summary: true,
+                },
+            },
+        }),
+    ],
+);
+
+class AllObsElement extends FASTElement {
+    public user = {
+        name: "Alice",
+    };
+
+    public settings = {
+        theme: "dark",
+    };
+
+    public updateUserName = () => {
+        this.user.name = "Bob";
+    };
+
+    public updateSettings = () => {
+        this.settings.theme = "light";
+    };
+}
+
+AllObsElement.define(
+    {
+        name: "all-obs-element",
+        template: declarativeTemplate(),
+    },
+    [observerMap()],
+);
+
+class EmptyPropsElement extends FASTElement {
+    public user = {
+        name: "Alice",
+    };
+
+    public settings = {
+        theme: "dark",
+    };
+
+    public updateUserName = () => {
+        this.user.name = "Bob";
+    };
+
+    public updateSettings = () => {
+        this.settings.theme = "light";
+    };
+}
+
+EmptyPropsElement.define(
+    {
+        name: "empty-props-element",
+        template: declarativeTemplate(),
+    },
+    [
+        observerMap({
+            properties: {},
+        }),
+    ],
+);
+
+class ArraySelectiveElement extends FASTElement {
+    public items: any[] = [
+        { text: "item-1", meta: { count: 1 } },
+        { text: "item-2", meta: { count: 2 } },
+    ];
+
+    public updateItemText = () => {
+        this.items[0].text = "updated-item-1";
+    };
+
+    public addItem = () => {
+        this.items.push({ text: "item-3", meta: { count: 3 } });
+    };
+}
+
+ArraySelectiveElement.define(
+    {
+        name: "array-selective-element",
+        template: declarativeTemplate(),
+    },
+    [
+        observerMap({
+            properties: {
+                items: true,
+            },
+        }),
+    ],
+);

package/test/declarative/fixtures/extensions/observer-map-properties/state.json

@@ -0,0 +1,29 @@
+{
+    "user": {
+        "name": "Alice",
+        "age": 28,
+        "history": {
+            "joined": "2020-01-01",
+            "visits": 100
+        },
+        "location": {
+            "city": "New York",
+            "country": "USA"
+        }
+    },
+    "settings": {
+        "theme": "dark",
+        "language": "en"
+    },
+    "analytics": {
+        "charts": {
+            "activeChart": "line",
+            "cachedData": "heavy-data"
+        },
+        "summary": "good"
+    },
+    "items": [
+        { "text": "item-1", "meta": { "count": 1 } },
+        { "text": "item-2", "meta": { "count": 2 } }
+    ]
+}

package/test/declarative/fixtures/extensions/observer-map-properties/templates.html

@@ -0,0 +1,55 @@
+<f-template name="selective-obs-element">
+    <template>
+        <div class="user-section">
+            <span class="user-name">{{user.name}}</span>
+            <span class="user-age">{{user.age}}</span>
+            <span class="user-history-joined">{{user.history.joined}}</span>
+            <span class="user-history-visits">{{user.history.visits}}</span>
+            <span class="user-location-city">{{user.location.city}}</span>
+        </div>
+        <div class="settings-section">
+            <span class="settings-theme">{{settings.theme}}</span>
+        </div>
+        <div class="analytics-section">
+            <span class="active-chart">{{analytics.charts.activeChart}}</span>
+            <span class="cached-data">{{analytics.charts.cachedData}}</span>
+            <span class="analytics-summary">{{analytics.summary}}</span>
+        </div>
+        <button @click="{updateUserName()}">Update Name</button>
+        <button @click="{updateUserAge()}">Update Age</button>
+        <button @click="{updateHistory()}">Update History</button>
+        <button @click="{updateLocation()}">Update Location</button>
+        <button @click="{updateSettings()}">Update Settings</button>
+        <button @click="{updateActiveChart()}">Update Active Chart</button>
+        <button @click="{updateCachedData()}">Update Cached Data</button>
+        <button @click="{updateSummary()}">Update Summary</button>
+    </template>
+</f-template>
+<f-template name="all-obs-element">
+    <template>
+        <span class="user-name">{{user.name}}</span>
+        <span class="settings-theme">{{settings.theme}}</span>
+        <button @click="{updateUserName()}">Update Name</button>
+        <button @click="{updateSettings()}">Update Settings</button>
+    </template>
+</f-template>
+<f-template name="empty-props-element">
+    <template>
+        <span class="user-name">{{user.name}}</span>
+        <span class="settings-theme">{{settings.theme}}</span>
+        <button @click="{updateUserName()}">Update Name</button>
+        <button @click="{updateSettings()}">Update Settings</button>
+    </template>
+</f-template>
+<f-template name="array-selective-element">
+    <template>
+        <f-repeat value="{{item in items}}">
+            <div class="item-row">
+                <span class="item-text">{{item.text}}</span>
+                <span class="item-count">{{item.meta.count}}</span>
+            </div>
+        </f-repeat>
+        <button @click="{updateItemText()}">Update Item Text</button>
+        <button @click="{addItem()}">Add Item</button>
+    </template>
+</f-template>

package/test/declarative/fixtures/scenarios/README.md

@@ -0,0 +1,7 @@
+# Scenarios
+
+Fixtures for complex scenarios that may involve multiple features interacting together and edge cases that arise from real-world usage patterns.
+
+| Fixture | Description |
+|---|---|
+| `nested-elements` | Nested custom elements with state propagation through shadow boundaries, event handling inside `f-repeat` with `$c.parent` context access, and `f-when` conditions within repeated content. |

package/test/declarative/fixtures/scenarios/nested-elements/entry.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Nested Elements Hydration Tests</title>
+    </head>
+    <body>
+        <parent-element category="{{category}}"></parent-element>
+        <parent-element title="Empty List" :items="{{emptyItems}}" category="{{category}}"></parent-element>
+        <parent-element title="Single Item" :items="{{singleItem}}" category="{{category}}"></parent-element>
+        <test-element-repeat-event></test-element-repeat-event>
+        <test-when-in-repeat></test-when-in-repeat>
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/test/declarative/fixtures/scenarios/nested-elements/fast-build.config.json

@@ -0,0 +1,6 @@
+{
+    "entry": "entry.html",
+    "state": "state.json",
+    "output": "index.html",
+    "templates": "templates.html"
+}

package/test/declarative/fixtures/scenarios/nested-elements/index.html

@@ -0,0 +1,126 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Nested Elements Hydration Tests</title>
+    </head>
+    <body>
+        <parent-element category="General"><template shadowrootmode="open" shadowroot="open"><div class="list-container">
+            <h2><!--fe:b-->My Items<!--fe:/b--></h2>
+            <div class="items">
+                <!--fe:b--><!--fe:r-->
+                    <child-element text="Item 1" idx="0" category="General" data-fe="3"><template shadowrootmode="open" shadowroot="open"><div class="item">
+            <span class="index"><!--fe:b-->0<!--fe:/b--></span>
+            <span class="text"><!--fe:b-->Item 1<!--fe:/b--></span>
+            <grand-child-element category="General" data-fe="1"><template shadowrootmode="open" shadowroot="open"><span class="category"><!--fe:b-->General<!--fe:/b--></span></template></grand-child-element>
+        </div></template></child-element>
+                <!--fe:/r--><!--fe:r-->
+                    <child-element text="Item 2" idx="1" category="General" data-fe="3"><template shadowrootmode="open" shadowroot="open"><div class="item">
+            <span class="index"><!--fe:b-->1<!--fe:/b--></span>
+            <span class="text"><!--fe:b-->Item 2<!--fe:/b--></span>
+            <grand-child-element category="General" data-fe="1"><template shadowrootmode="open" shadowroot="open"><span class="category"><!--fe:b-->General<!--fe:/b--></span></template></grand-child-element>
+        </div></template></child-element>
+                <!--fe:/r--><!--fe:r-->
+                    <child-element text="Item 3" idx="2" category="General" data-fe="3"><template shadowrootmode="open" shadowroot="open"><div class="item">
+            <span class="index"><!--fe:b-->2<!--fe:/b--></span>
+            <span class="text"><!--fe:b-->Item 3<!--fe:/b--></span>
+            <grand-child-element category="General" data-fe="1"><template shadowrootmode="open" shadowroot="open"><span class="category"><!--fe:b-->General<!--fe:/b--></span></template></grand-child-element>
+        </div></template></child-element>
+                <!--fe:/r--><!--fe:/b-->
+            </div>
+        </div></template></parent-element>
+        <parent-element title="Empty List" category="General"><template shadowrootmode="open" shadowroot="open"><div class="list-container">
+            <h2><!--fe:b-->Empty List<!--fe:/b--></h2>
+            <div class="items">
+                <!--fe:b--><!--fe:/b-->
+            </div>
+        </div></template></parent-element>
+        <parent-element title="Single Item" category="General"><template shadowrootmode="open" shadowroot="open"><div class="list-container">
+            <h2><!--fe:b-->Single Item<!--fe:/b--></h2>
+            <div class="items">
+                <!--fe:b--><!--fe:r-->
+                    <child-element text="Only Item" idx="0" category="General" data-fe="3"><template shadowrootmode="open" shadowroot="open"><div class="item">
+            <span class="index"><!--fe:b-->0<!--fe:/b--></span>
+            <span class="text"><!--fe:b-->Only Item<!--fe:/b--></span>
+            <grand-child-element category="General" data-fe="1"><template shadowrootmode="open" shadowroot="open"><span class="category"><!--fe:b-->General<!--fe:/b--></span></template></grand-child-element>
+        </div></template></child-element>
+                <!--fe:/r--><!--fe:/b-->
+            </div>
+        </div></template></parent-element>
+        <test-element-repeat-event><template shadowrootmode="open" shadowroot="open"><ul>
+            <!--fe:b--><!--fe:/b-->
+        </ul></template></test-element-repeat-event>
+        <test-when-in-repeat><template shadowrootmode="open" shadowroot="open"><ul>
+            <!--fe:b--><!--fe:r-->
+                <li>
+                    <!--fe:b-->
+                        <button class="name" type="button" data-fe="1"><!--fe:b-->Alpha<!--fe:/b--></button>
+                    <!--fe:/b-->
+                </li>
+            <!--fe:/r--><!--fe:r-->
+                <li>
+                    <!--fe:b-->
+                        <button class="name" type="button" data-fe="1"><!--fe:b-->Beta<!--fe:/b--></button>
+                    <!--fe:/b-->
+                </li>
+            <!--fe:/r--><!--fe:/b-->
+        </ul></template></test-when-in-repeat>
+<f-template name="test-element-repeat-event">
+    <template>
+        <ul>
+            <f-repeat value="{{item in repeatEventItems}}">
+                <li>
+                    <button type="button" @click="{$c.parent.handleItemClick($e)}">{{item.name}}</button>
+                </li>
+            </f-repeat>
+        </ul>
+    </template>
+</f-template>
+<f-template name="test-when-in-repeat">
+    <template>
+        <ul>
+            <f-repeat value="{{item in whenRepeatItems}}">
+                <li>
+                    <f-when value="{{showNames}}">
+                        <button class="name" type="button" @click="{$c.parent.handleItemClick($e)}">{{item.name}}</button>
+                    </f-when>
+                </li>
+            </f-repeat>
+        </ul>
+    </template>
+</f-template>
+<f-template name="grand-child-element">
+    <template>
+        <span class="category">{{category}}</span>
+    </template>
+</f-template>
+<f-template name="child-element">
+    <template>
+        <div class="item">
+            <span class="index">{{idx}}</span>
+            <span class="text">{{text}}</span>
+            <grand-child-element category="{{category}}"></grand-child-element>
+        </div>
+    </template>
+</f-template>
+<f-template name="parent-element">
+    <template>
+        <div class="list-container">
+            <h2>{{title}}</h2>
+            <div class="items">
+                <f-repeat value="{{item in items}}" positioning="true">
+                    <child-element
+                        text="{{item.text}}"
+                        idx="{{$index}}"
+                        category="{{category}}"
+                    ></child-element>
+                </f-repeat>
+            </div>
+        </div>
+    </template>
+</f-template>
+
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/test/declarative/fixtures/scenarios/nested-elements/main.ts

@@ -0,0 +1,214 @@
+import { attr } from "@microsoft/fast-element/attr.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { deepMerge } from "@microsoft/fast-element/declarative-utilities.js";
+import { FASTElement } from "@microsoft/fast-element/fast-element.js";
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
+import { observable } from "@microsoft/fast-element/observable.js";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
+
+(window as any).messages = [];
+
+const lifecycleCallbacks = {
+    elementDidDefine(name: string) {
+        (window as any).messages.push(
+            `Element did define: ${name} [${performance.now()}]`,
+        );
+    },
+    elementDidRegister(name: string) {
+        (window as any).messages.push(
+            `Element did register: ${name} [${performance.now()}]`,
+        );
+    },
+    templateDidUpdate(name: string) {
+        (window as any).messages.push(
+            `Template did update: ${name} [${performance.now()}]`,
+        );
+    },
+    templateWillUpdate(name: string) {
+        (window as any).messages.push(
+            `Template will update: ${name} [${performance.now()}]`,
+        );
+    },
+};
+
+enableHydration({
+    hydrationComplete() {
+        (window as any).messages.push(`Hydration complete [${performance.now()}]`);
+        (window as any).hydrationCompleted = true;
+    },
+});
+
+// Mock data sources - simulating fetched data
+const mockDataSources = {
+    getListData(listId: string) {
+        const dataSets: Record<
+            string,
+            { title: string; items: Array<{ text: string }> }
+        > = {
+            "list-1": {
+                title: "My Items",
+                items: [{ text: "Item 1" }, { text: "Item 2" }, { text: "Item 3" }],
+            },
+            "list-2": {
+                title: "Empty List",
+                items: [],
+            },
+            "list-3": {
+                title: "Single Item",
+                items: [{ text: "Only Item" }],
+            },
+        };
+        return dataSets[listId] || { title: "Unknown List", items: [] };
+    },
+    getItemData(itemId: string) {
+        // Simulate fetching individual item data
+        return { text: `Loaded: ${itemId}`, timestamp: Date.now() };
+    },
+    getItemById(itemId: string) {
+        // Simulate fetching item data by ID
+        const itemDataMap: Record<string, { text: string; idx: number }> = {
+            "item-1": { text: "Item 1", idx: 0 },
+            "item-2": { text: "Item 2", idx: 1 },
+            "item-3": { text: "Item 3", idx: 2 },
+            "item-4": { text: "Only Item", idx: 0 },
+        };
+        return itemDataMap[itemId] || { text: "Unknown", idx: 0 };
+    },
+};
+
+export class ItemList extends FASTElement {
+    @observable
+    public items: Array<{ text: string }> = [];
+
+    @observable
+    public title: string = "";
+
+    @attr
+    public category!: string;
+
+    // Track which list instance this is (1st, 2nd, or 3rd on the page)
+    private static connectedCallCount = 0;
+    private static instanceMap = new WeakMap<ItemList, number>();
+
+    connectedCallback() {
+        if (!ItemList.instanceMap.has(this)) {
+            ItemList.connectedCallCount++;
+            ItemList.instanceMap.set(this, ItemList.connectedCallCount);
+        }
+
+        const instanceNumber = ItemList.instanceMap.get(this) || 0;
+        const listIds = ["list-1", "list-2", "list-3"];
+        const listId = listIds[instanceNumber - 1] || "list-1";
+        const data = mockDataSources.getListData(listId);
+
+        // Set data BEFORE super so items are in _items before
+        // ElementController.bindObservables replays boundObservables
+        this.title = data.title;
+        this.items = data.items;
+
+        super.connectedCallback();
+    }
+}
+
+export class Item extends FASTElement {
+    @observable
+    public text: string = "";
+
+    @observable
+    public idx: number = 0;
+
+    @attr
+    public category!: string;
+
+    // Track which item instance this is globally
+    private static connectedCallCount = 0;
+    private static instanceMap = new WeakMap<Item, number>();
+
+    connectedCallback() {
+        if (!Item.instanceMap.has(this)) {
+            Item.connectedCallCount++;
+            Item.instanceMap.set(this, Item.connectedCallCount);
+        }
+
+        const instanceNumber = Item.instanceMap.get(this) || 0;
+        const itemIds = ["item-1", "item-2", "item-3", "item-4"];
+        const itemId = itemIds[instanceNumber - 1] || "item-1";
+        const data = mockDataSources.getItemById(itemId);
+
+        // Set data before super so it's available during hydration
+        deepMerge(this, data);
+
+        super.connectedCallback();
+    }
+}
+
+export class GrandChildItem extends FASTElement {
+    @attr
+    public category!: string;
+}
+
+export interface RepeatItemType {
+    name: string;
+}
+
+export class TestElementRepeatEvent extends FASTElement {
+    @observable
+    repeatEventItems: Array<RepeatItemType> = [];
+
+    @observable
+    clickedItemName: string = "";
+
+    // Called via $c.parent.handleItemClick — `this` is bound to the host
+    // because the $c.parent path resolves the method owner from the context.
+    handleItemClick(e: Event) {
+        this.clickedItemName = (e.currentTarget as HTMLButtonElement).textContent!;
+    }
+}
+TestElementRepeatEvent.define({
+    name: "test-element-repeat-event",
+    template: declarativeTemplate(lifecycleCallbacks),
+});
+
+export class TestWhenInRepeat extends FASTElement {
+    @observable whenRepeatItems: Array<RepeatItemType> = [
+        { name: "Alpha" },
+        { name: "Beta" },
+    ];
+    @observable showNames: boolean = true;
+    @observable clickedItemName: string = "";
+
+    handleItemClick(e: Event) {
+        this.clickedItemName = (e.currentTarget as HTMLButtonElement).textContent!;
+    }
+}
+TestWhenInRepeat.define(
+    {
+        name: "test-when-in-repeat",
+        template: declarativeTemplate(lifecycleCallbacks),
+    },
+    [observerMap()],
+);
+
+ItemList.define(
+    {
+        name: "parent-element",
+        template: declarativeTemplate(lifecycleCallbacks),
+    },
+    [observerMap()],
+);
+
+Item.define(
+    {
+        name: "child-element",
+        template: declarativeTemplate(lifecycleCallbacks),
+    },
+    [observerMap()],
+);
+
+GrandChildItem.define(
+    {
+        name: "grand-child-element",
+        template: declarativeTemplate(lifecycleCallbacks),
+    },
+    [observerMap()],
+);

package/test/declarative/fixtures/scenarios/nested-elements/state.json

@@ -0,0 +1,10 @@
+{
+    "title": "My Items",
+    "items": [{ "text": "Item 1" }, { "text": "Item 2" }, { "text": "Item 3" }],
+    "emptyItems": [],
+    "singleItem": [{ "text": "Only Item" }],
+    "category": "General",
+    "repeatEventItems": [],
+    "whenRepeatItems": [{ "name": "Alpha" }, { "name": "Beta" }],
+    "showNames": true
+}