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

package/test/declarative/fixtures/WRITING_FIXTURES.md

@@ -0,0 +1,330 @@
+# Writing Fixtures
+
+This guide explains how to create and maintain Playwright test fixtures for the
+declarative runtime in `@microsoft/fast-element`. Each fixture is a
+self-contained test case that exercises a specific feature through a live Vite
+dev server.
+
+## Fixture structure
+
+Every fixture lives in a category subdirectory under
+`test/declarative/fixtures/`:
+
+```
+test/declarative/fixtures/<category>/<feature>/
+├── <feature>.spec.ts        # Playwright test
+├── entry.html               # Entry template — input to the build step
+├── fast-build.config.json   # Build configuration for @microsoft/fast-build
+├── index.html               # Pre-rendered page — GENERATED, do not edit
+├── main.ts                  # Component definitions and setup
+├── state.json               # Initial state for server-side rendering
+└── templates.html           # Declarative <f-template> definitions
+```
+
+Fixtures are organized into five categories:
+
+| Category | Description | Details |
+|---|---|---|
+| `bindings/` | Various binding types (attribute, content, event, etc.) | [README](./bindings/README.md) |
+| `scenarios/` | Complex scenarios with edge cases involving multiple features | [README](./scenarios/README.md) |
+| `directives/` | Attribute and element directives (`f-repeat`, `f-when`, `f-ref`, etc.) | [README](./directives/README.md) |
+| `extensions/` | Additional functionality beyond direct configuration (attribute maps, observer maps) | [README](./extensions/README.md) |
+| `ecosystem/` | Other ecosystem APIs (errors, lifecycle, performance) | [README](./ecosystem/README.md) |
+
+> **Important:** `index.html` is generated by `npm run build:fixtures`. Never edit it by hand — your changes will be overwritten on the next build. If something looks wrong in `index.html`, fix the source files (`entry.html`, `state.json`, `templates.html`) and rebuild.
+
+---
+
+## Creating a new fixture
+
+1. Create a new directory under `test/declarative/fixtures/<category>/` with a
+   descriptive kebab-case name (e.g., `bindings/my-feature/`).
+2. Add the required files described below.
+3. Run `npm run build:fixtures -w @microsoft/fast-element` to generate
+   `index.html`.
+4. Write your Playwright tests in `<feature>.spec.ts`.
+5. Run `npm run test:chromium:declarative -w @microsoft/fast-element` to verify
+   everything works.
+
+Fixtures are auto-discovered by scanning category directories for subdirectories that contain `entry.html`, `templates.html`, `state.json`, and `fast-build.config.json`. Both the build script and the Vite config pick up new fixtures automatically — no registration step is needed.
+
+---
+
+## fast-build.config.json
+
+Each fixture must include a `fast-build.config.json` file that tells the `@microsoft/fast-build` CLI where to find the fixture's source files and how to build them. The build script passes `--config=<path>` to the CLI for each fixture.
+
+### Standard config
+
+Most fixtures use the same standard configuration:
+
+```json
+{
+    "entry": "entry.html",
+    "state": "state.json",
+    "output": "index.html",
+    "templates": "templates.html"
+}
+```
+
+### Fixture-specific options
+
+If a fixture needs custom build options (e.g., an attribute name strategy), add them to the config:
+
+```json
+{
+    "entry": "entry.html",
+    "state": "state.json",
+    "output": "index.html",
+    "templates": "templates.html",
+    "attribute-name-strategy": "camelCase"
+}
+```
+
+Allowed keys: `entry`, `state`, `output`, `templates`, `attribute-name-strategy`. All values must be strings. File paths are resolved relative to the config file's directory.
+
+> **Note:** Fixture configs must use the standard file names (`entry.html`, `state.json`, `index.html`, `templates.html`) because the build scripts and WebUI integration rely on these conventions for template injection and cross-renderer testing.
+
+---
+
+## entry.html
+
+The entry file is a minimal HTML document that places your custom elements on the page. It serves as the input to the server-side renderer.
+
+```html
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <title></title>
+    </head>
+    <body>
+        <my-element greeting="{{greeting}}"></my-element>
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>
+```
+
+### Attribute binding guidelines
+
+When writing attribute bindings on root elements in `entry.html`:
+
+| Pattern | Guidance |
+|---|---|
+| `type="{{type}}"` (primitive same-name) | ✅ Fine — rendered onto the opening tag for `@attr` initialization. |
+| `list="{{list}}"` (complex same-name) | ❌ Unnecessary — non-primitive values are stripped from the rendered tag; state propagation provides them automatically. |
+| `foo="{{bar}}"` (rename) | ❌ Avoid — rename `bar` to `foo` in `state.json` instead. |
+| `:items="{{emptyItems}}"` (property binding) | ✅ Acceptable when multiple instances of the same element need different values for the same property. |
+
+---
+
+## state.json
+
+A JSON object containing the initial state that the server-side renderer uses to evaluate bindings. Property names should match what the templates and entry HTML reference.
+
+```json
+{
+    "greeting": "Hello",
+    "isEnabled": true,
+    "items": ["A", "B", "C"]
+}
+```
+
+Keep `state.json` minimal — only include values that affect the pre-rendered output. Complex objects (arrays, nested data) are supported.
+
+---
+
+## templates.html
+
+This file defines the declarative `<f-template>` elements that describe each custom element's shadow DOM. Each `<f-template>` has a `name` attribute matching the custom element tag name and contains a `<template>` child with the component's markup.
+
+```html
+<f-template name="my-element">
+    <template>
+        <span>{{greeting}}</span>
+    </template>
+</f-template>
+```
+
+### Template syntax
+
+For a full reference of binding syntax, event bindings, directives (`f-when`,
+`f-repeat`), and execution context access, see the [Syntax section of the
+declarative docs](../../../DECLARATIVE_HTML.md#syntax).
+
+Multiple `<f-template>` elements can be defined in a single `templates.html` — one per custom element used in the fixture.
+
+---
+
+## main.ts
+
+The component definition file registers custom elements and configures the template system. Every fixture must:
+
+1. Define element classes extending `FASTElement`.
+2. Call `define()` on the element class with `template: declarativeTemplate()`.
+3. Use `declarativeTemplate(callbacks)` for per-element lifecycle callbacks,
+   `enableHydration()` for hydration callbacks, and define extensions such as
+   `attributeMap()` / `observerMap()` for schema behavior.
+   `declarativeTemplate()` registers FAST's internal `<f-template>` publisher
+   automatically.
+
+### Import paths
+
+> **Important:** All imports in `main.ts` must use package names (for example
+> `@microsoft/fast-element`), **not** relative paths.
+> Relative imports will break the WebUI integration tests because fixtures are
+> copied to a different directory structure during the integration build. The
+> same applies to any other paths referenced in `main.ts`.
+
+### Basic pattern
+
+```typescript
+import {
+    FASTElement,
+    attr,
+    observable,
+} from "@microsoft/fast-element";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+
+class MyElement extends FASTElement {
+    @attr
+    greeting: string = "Hello";
+}
+MyElement.define({
+    name: "my-element",
+    template: declarativeTemplate(),
+});
+```
+
+### When to use `@attr` vs `@observable`
+
+- Use `@attr` for values reflected as HTML attributes (strings, booleans) — these can be set in `entry.html`.
+- Use `@observable` for internal state or complex values (arrays, objects) — these are provided via `state.json`.
+
+### Exporting types
+
+If your spec file needs to reference element types (e.g., for `page.evaluate` calls), export the classes:
+
+```typescript
+export class TestElement extends FASTElement {
+    @observable
+    list: Array<string> = [];
+}
+```
+
+Then import in the spec:
+
+```typescript
+import type { TestElement } from "./main.js";
+
+await customElement.evaluate((node: TestElement) => {
+    node.list = ["A", "B", "C"];
+});
+```
+
+### Using ObserverMap
+
+For fixtures that test deeply nested property reactivity, prefer the
+definition-scoped `observerMap()` extension:
+
+```typescript
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
+
+MyElement.define(
+    {
+        name: "my-element",
+        template: declarativeTemplate(),
+    },
+    [observerMap()],
+);
+```
+
+This enables the `ObserverMap` proxy system to track nested property changes without requiring `@observable` decorators on every property.
+
+---
+
+## Writing the spec file
+
+Spec files use Playwright's test runner. Each fixture's tests navigate to the fixture page and interact with the rendered components.
+
+### Basic structure
+
+```typescript
+import { expect, test } from "@playwright/test";
+
+test.describe("my-feature", async () => {
+    test("initial render is correct", async ({ page }) => {
+        await page.goto("/fixtures/bindings/my-feature/");
+
+        const element = page.locator("my-element");
+        await expect(element).toHaveText("Hello");
+    });
+
+    test("responds to attribute changes", async ({ page }) => {
+        await page.goto("/fixtures/bindings/my-feature/");
+
+        const element = page.locator("my-element");
+
+        await page.evaluate(() => {
+            document
+                .querySelector("my-element")!
+                .setAttribute("greeting", "World");
+        });
+
+        await expect(element).toHaveText("World");
+    });
+});
+```
+
+### Common patterns
+
+- **Navigate to the fixture:** `await page.goto("/fixtures/<category>/<feature>/");`
+- **Locate elements:** `page.locator("my-element")` or `page.locator("#specific-id")`
+- **Modify attributes:** `await page.evaluate(() => { element.setAttribute(...) })`
+- **Modify properties:** `await element.evaluate((node: MyElement) => { node.prop = value })`
+- **Assert text:** `await expect(element).toHaveText("expected")`
+- **Assert attributes:** `await expect(element).toHaveAttribute("attr", "value")`
+- **Assert child count:** `await expect(element.locator("li")).toHaveCount(3)`
+
+---
+
+## Rebuilding fixtures
+
+After editing `entry.html`, `templates.html`, `state.json`, or `fast-build.config.json`, you **must** regenerate `index.html`:
+
+```bash
+npm run build:fixtures -w @microsoft/fast-element
+```
+
+This invokes `@microsoft/fast-build` for each auto-discovered fixture with `--config` pointing to the fixture's `fast-build.config.json`. The CLI reads the config file to locate the entry template, state, template definitions, and output path, then renders the output. The build script then injects the `<f-template>` declarations from `templates.html` before the `<script>` tag in the generated output. Fixtures are discovered automatically by scanning category subdirectories for directories that contain `entry.html`, `templates.html`, `state.json`, and `fast-build.config.json`.
+
+> **Tip:** If you're iterating on a fixture, use
+> `npm run dev:declarative -w @microsoft/fast-element` to start the Vite dev
+> server with file watching. But remember to run `build:fixtures` before
+> committing — the Vite dev server uses the generated `index.html`.
+
+### WebUI integration
+
+The same fixtures are also validated against `@microsoft/webui` to ensure cross-renderer compatibility. To build and test fixtures with webui:
+
+```bash
+# Build fixtures with webui and run Playwright tests
+npm run test:webui-integration -w @microsoft/fast-element
+
+# Or run the steps separately
+npm run build:fixtures:webui -w @microsoft/fast-element
+npm exec -w @microsoft/fast-element -- playwright test --config=playwright.declarative.webui.config.ts
+```
+
+The webui build step (`scripts/build-fixtures-with-webui.js`) extracts `<f-template>` elements, builds each fixture with `webui build --plugin=fast`, renders the output with `state.json`, and writes the result to `temp/integrations/webui/fixtures/`. The existing Playwright specs then run against this output.
+
+---
+
+## Checklist for new fixtures
+
+- [ ] Created fixture directory within the appropriate category with all required files (including `fast-build.config.json`)
+- [ ] Ran `npm run build:fixtures -w @microsoft/fast-element` to generate `index.html`
+- [ ] Wrote Playwright tests in `<feature>.spec.ts`
+- [ ] Tests pass locally with `npm run test:chromium:declarative -w @microsoft/fast-element`
+- [ ] Committed all files **including** the generated `index.html`

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

@@ -0,0 +1,12 @@
+# Bindings
+
+Fixtures for testing the various binding types supported by FAST Element's
+declarative templates.
+
+| Fixture | Description |
+|---|---|
+| `attribute` | Attribute binding via `@attr` and `@observable` decorators on custom elements. |
+| `content` | Content binding with `{{text}}` for escaped HTML and `{{{html}}}` for unescaped HTML injection. |
+| `dot-syntax` | Dot-notation path access in bindings (e.g., `{{user.name}}`, `{{user.address.city}}`). |
+| `event` | Event binding syntax with `@click="{handleClick()}"`, DOM event access via `$e`, and context access via `$c`. |
+| `host` | Host element bindings for applying styles and attributes to the host element. |

package/test/declarative/fixtures/bindings/attribute/entry.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <title></title>
+    </head>
+    <body>
+        <test-element type="{{type}}"></test-element>
+        <test-element-property></test-element-property>
+        <test-element-expression></test-element-expression>
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/test/declarative/fixtures/bindings/attribute/fast-build.config.json

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

package/test/declarative/fixtures/bindings/attribute/index.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <title></title>
+    </head>
+    <body>
+        <test-element type="checkbox"><template shadowrootmode="open" shadowroot="open"><input type="checkbox" disabled data-fe="1"></template></test-element>
+        <test-element-property><template shadowrootmode="open" shadowroot="open"><input type="checkbox" disabled data-fe="1"></template></test-element-property>
+        <test-element-expression><template shadowrootmode="open" shadowroot="open"><input disabled type="button" data-fe="1"></template></test-element-expression>
+<f-template name="test-element">
+    <template> <input type="{{type}}" disabled> </template>
+</f-template>
+<f-template name="test-element-property">
+    <template> <input type="checkbox" ?disabled="{{!isEnabled}}"> </template>
+</f-template>
+<f-template name="test-element-expression">
+    <template>
+        <input ?disabled="{{activeGroup == currentGroup}}" type="button">
+    </template>
+</f-template>
+
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/test/declarative/fixtures/bindings/attribute/main.ts

@@ -0,0 +1,41 @@
+import { attr } from "@microsoft/fast-element/attr.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.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";
+
+class TestElement extends FASTElement {
+    @attr
+    type: string = "radio";
+}
+TestElement.define({
+    name: "test-element",
+    template: declarativeTemplate(),
+});
+
+class TestElementProperty extends FASTElement {
+    @observable
+    isEnabled: boolean = false;
+}
+TestElementProperty.define({
+    name: "test-element-property",
+    template: declarativeTemplate(),
+});
+
+class TestElementExpression extends FASTElement {
+    @attr({ attribute: "active-group" })
+    activeGroup: string = "";
+
+    @attr({ attribute: "current-group" })
+    currentGroup: string = "";
+}
+TestElementExpression.define({
+    name: "test-element-expression",
+    template: declarativeTemplate(),
+});
+
+enableHydration({
+    hydrationComplete() {
+        (window as any).hydrationCompleted = true;
+    },
+});

package/test/declarative/fixtures/bindings/attribute/state.json

@@ -0,0 +1,8 @@
+{
+    "type": "checkbox",
+    "active-group": "work",
+    "current-group": "work",
+    "activeGroup": "work",
+    "currentGroup": "work",
+    "isEnabled": false
+}

package/test/declarative/fixtures/bindings/attribute/templates.html

@@ -0,0 +1,11 @@
+<f-template name="test-element">
+    <template> <input type="{{type}}" disabled> </template>
+</f-template>
+<f-template name="test-element-property">
+    <template> <input type="checkbox" ?disabled="{{!isEnabled}}"> </template>
+</f-template>
+<f-template name="test-element-expression">
+    <template>
+        <input ?disabled="{{activeGroup == currentGroup}}" type="button">
+    </template>
+</f-template>

package/test/declarative/fixtures/bindings/content/entry.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <title></title>
+    </head>
+    <body>
+        <test-element text="{{text}}"></test-element>
+        <test-element-unescaped html="{{html}}"></test-element-unescaped>
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/test/declarative/fixtures/bindings/content/fast-build.config.json

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

package/test/declarative/fixtures/bindings/content/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <title></title>
+    </head>
+    <body>
+        <test-element text="Hello world"><template shadowrootmode="open" shadowroot="open"><!--fe:b-->Hello world<!--fe:/b--></template></test-element>
+        <test-element-unescaped html="&lt;p&gt;Hello world&lt;/p&gt;"><template shadowrootmode="open" shadowroot="open"><!--fe:b--><p>Hello world</p><!--fe:/b--></template></test-element-unescaped>
+<f-template name="test-element">
+    <template>{{text}}</template>
+</f-template>
+<f-template name="test-element-unescaped">
+    <template>{{{html}}}</template>
+</f-template>
+
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/test/declarative/fixtures/bindings/content/main.ts

@@ -0,0 +1,27 @@
+import { attr } from "@microsoft/fast-element/attr.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { FASTElement } from "@microsoft/fast-element/fast-element.js";
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
+
+class TestElement extends FASTElement {
+    @attr
+    text: string = "Hello";
+}
+TestElement.define({
+    name: "test-element",
+    template: declarativeTemplate(),
+});
+
+class TestElementUnescaped extends FASTElement {
+    public html = `<p>Hello world</p>`;
+}
+TestElementUnescaped.define({
+    name: "test-element-unescaped",
+    template: declarativeTemplate(),
+});
+
+enableHydration({
+    hydrationComplete() {
+        (window as any).hydrationCompleted = true;
+    },
+});

package/test/declarative/fixtures/bindings/content/state.json

@@ -0,0 +1,4 @@
+{
+    "text": "Hello world",
+    "html": "<p>Hello world</p>"
+}

package/test/declarative/fixtures/bindings/content/templates.html

@@ -0,0 +1,6 @@
+<f-template name="test-element">
+    <template>{{text}}</template>
+</f-template>
+<f-template name="test-element-unescaped">
+    <template>{{{html}}}</template>
+</f-template>

package/test/declarative/fixtures/bindings/dot-syntax/entry.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <title></title>
+    </head>
+    <body>
+        <test-element></test-element>
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/test/declarative/fixtures/bindings/dot-syntax/fast-build.config.json

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

package/test/declarative/fixtures/bindings/dot-syntax/index.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <title></title>
+    </head>
+    <body>
+        <test-element><template shadowrootmode="open" shadowroot="open"><span><!--fe:b-->bar<!--fe:/b--></span>
+        <span><!--fe:b--><!--fe:/b--></span>
+        <span><!--fe:b-->FOO<!--fe:/b--></span>
+        <button data-fe="1">Set b</button>
+        <button data-fe="1">Set a.b1</button>
+        <button data-fe="1">Set a.b2.c</button>
+        <!--fe:b-->
+            <!--fe:b--><!--fe:r-->
+                <!--fe:b-->
+                    <div><!--fe:b-->Item 1<!--fe:/b--></div>
+                <!--fe:/b-->
+            <!--fe:/r--><!--fe:r-->
+                <!--fe:b-->
+                    <div><!--fe:b-->Item 2<!--fe:/b--></div>
+                <!--fe:/b-->
+            <!--fe:/r--><!--fe:r-->
+                <!--fe:b--><!--fe:/b-->
+            <!--fe:/r--><!--fe:/b-->
+        <!--fe:/b--></template></test-element>
+<f-template name="test-element">
+    <template>
+        <span>{{object.b}}</span>
+        <span>{{object.a.b1}}</span>
+        <span>{{object.a.b2.c}}</span>
+        <button @click="{handleBClick()}">Set b</button>
+        <button @click="{handleAB1Click()}">Set a.b1</button>
+        <button @click="{handleAB2CClick()}">Set a.b2.c</button>
+        <f-when value="{{object.c}}">
+            <f-repeat value="{{item in object.c}}">
+                <f-when value="{{item.name && item.status == 'active'}}">
+                    <div>{{item.name}}</div>
+                </f-when>
+            </f-repeat>
+        </f-when>
+    </template>
+</f-template>
+
+        <script type="module" src="./main.ts"></script>
+    </body>
+</html>

package/test/declarative/fixtures/bindings/dot-syntax/main.ts

@@ -0,0 +1,59 @@
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { FASTElement } from "@microsoft/fast-element/fast-element.js";
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
+
+class TestElement extends FASTElement {
+    public object: any = {
+        a: {
+            b2: {
+                c: "FOO",
+            },
+        },
+        b: "bar",
+        c: [
+            {
+                name: "Item 1",
+                status: "active",
+            },
+            {
+                name: "Item 2",
+                status: "active",
+            },
+            {
+                status: "active",
+            },
+        ],
+    };
+
+    public handleBClick = () => {
+        this.object.b = "Hello";
+    };
+
+    public handleAB1Click = () => {
+        if (this.object.a) {
+            this.object.a.b1 = "World";
+        } else {
+            this.object.a = {
+                b1: "World",
+            };
+        }
+    };
+
+    public handleAB2CClick = () => {
+        this.object.a.b2.c = "Pluto";
+    };
+}
+TestElement.define(
+    {
+        name: "test-element",
+        template: declarativeTemplate(),
+    },
+    [observerMap()],
+);
+
+enableHydration({
+    hydrationComplete() {
+        (window as any).hydrationCompleted = true;
+    },
+});