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

package/playwright.declarative.webui.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig, devices } from "@playwright/test";
+
+process.env.FAST_WEBUI_INTEGRATION = "true";
+
+export default defineConfig({
+    testDir: "./test/declarative/fixtures",
+    testMatch: "**/*.spec.ts",
+    retries: 3,
+    projects: [
+        {
+            name: "chromium",
+            use: { ...devices["Desktop Chrome"] },
+        },
+    ],
+    webServer: {
+        command: "npm run test-server:declarative:webui",
+        port: 5174,
+        reuseExistingServer: true,
+    },
+});

package/scripts/declarative/build-fixtures-with-webui.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+/**
+ * Build FAST HTML fixtures with @microsoft/webui.
+ *
+ * For each fixture directory this script:
+ *   1. Extracts <f-template> components from templates.html into individual
+ *      component files (webui uses filename-based component discovery).
+ *   2. Builds the fixture with `webui build --plugin=fast`.
+ *   3. Renders the compiled protocol with the fixture's state.json.
+ *   4. Writes the rendered index.html into temp/integrations/webui/fixtures/
+ *      alongside a copy of main.ts and any extra assets so that Playwright
+ *      tests can run against the webui-rendered output via Vite.
+ */
+
+import {
+    copyFileSync,
+    existsSync,
+    mkdirSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build, render } from "@microsoft/webui";
+import {
+    convertToWebuiSyntax,
+    discoverFixtures,
+    extractFTemplates,
+} from "./build-fixtures.utilities.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixturesDir = resolve(__dirname, "../../test/declarative/fixtures");
+const fixtures = discoverFixtures(fixturesDir);
+const outBase = resolve(__dirname, "../../temp/integrations/webui/fixtures");
+
+// Files produced by the build or only needed for the build step.
+const buildOnlyFiles = new Set([
+    "entry.html",
+    "fast-build.config.json",
+    "templates.html",
+    "state.json",
+    "index.html",
+]);
+
+/**
+ * Build a single fixture with webui and write the rendered output plus
+ * supporting files into the output directory.
+ */
+function buildFixture(fixtureName) {
+    const fixtureDir = join(fixturesDir, fixtureName);
+    const buildDir = join(outBase, ".build", fixtureName);
+    const buildOutDir = join(buildDir, "out");
+    const fixtureOutDir = join(outBase, fixtureName);
+
+    mkdirSync(buildDir, { recursive: true });
+    mkdirSync(buildOutDir, { recursive: true });
+    mkdirSync(fixtureOutDir, { recursive: true });
+
+    // Extract individual component HTML files for webui discovery,
+    // converting FAST directives to webui syntax.
+    const templatesHtml = readFileSync(join(fixtureDir, "templates.html"), "utf8");
+    const templates = extractFTemplates(templatesHtml);
+
+    for (const { name, content } of templates) {
+        writeFileSync(join(buildDir, `${name}.html`), convertToWebuiSyntax(content));
+    }
+
+    // Prepare entry.html without script tags for webui build
+    const entryHtml = readFileSync(join(fixtureDir, "entry.html"), "utf8");
+    const cleanedEntry = entryHtml
+        .split("\n")
+        .filter(line => !line.includes("<script"))
+        .join("\n");
+    writeFileSync(join(buildDir, "entry.html"), cleanedEntry);
+
+    // Build protocol
+    const buildResult = build({
+        appDir: buildDir,
+        entry: "entry.html",
+        plugin: "fast",
+        outDir: buildOutDir,
+    });
+
+    if (!buildResult.protocol || buildResult.protocol.length === 0) {
+        throw new Error(`Build produced empty protocol for "${fixtureName}"`);
+    }
+
+    // Render with state
+    const state = JSON.parse(readFileSync(join(fixtureDir, "state.json"), "utf8"));
+    let html = render(buildResult.protocol, state, {
+        plugin: "fast",
+        entry: "entry.html",
+    });
+
+    // Inject <script type="module" src="./main.ts"> before </body>
+    html = html.replace(
+        "</body>",
+        '<script type="module" src="./main.ts"></script>\n</body>',
+    );
+
+    writeFileSync(join(fixtureOutDir, "index.html"), html);
+
+    // Copy main.ts and any extra assets (CSS, SVG, etc.) from the
+    // original fixture directory so Vite can serve them.
+    for (const entry of readdirSync(fixtureDir)) {
+        if (buildOnlyFiles.has(entry) || entry.endsWith(".spec.ts")) {
+            continue;
+        }
+        copyFileSync(join(fixtureDir, entry), join(fixtureOutDir, entry));
+    }
+
+    process.stdout.write(`Fixture "${fixtureName}" built successfully.\n`);
+}
+
+function main() {
+    // Clean previous build output
+    if (existsSync(outBase)) {
+        rmSync(outBase, { recursive: true });
+    }
+
+    for (const fixtureName of fixtures) {
+        buildFixture(fixtureName);
+    }
+
+    // Clean up intermediate build directory
+    const buildTmp = join(outBase, ".build");
+    if (existsSync(buildTmp)) {
+        rmSync(buildTmp, { recursive: true });
+    }
+}
+
+main();

package/scripts/declarative/build-fixtures.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverFixtures } from "./build-fixtures.utilities.js";
+
+// Pass-through CLI arguments (forwarded to every fast-build invocation).
+const passthroughArgs = process.argv.slice(2);
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixturesDir = resolve(__dirname, "../../test/declarative/fixtures");
+const fixtures = discoverFixtures(fixturesDir);
+
+const require = createRequire(import.meta.url);
+const fastBin = require.resolve("@microsoft/fast-build/bin/fast.js");
+
+for (const fixtureName of fixtures) {
+    const fixtureDir = resolve(__dirname, "../../test/declarative/fixtures", fixtureName);
+    const configFile = join(fixtureDir, "fast-build.config.json");
+    const templatesFile = join(fixtureDir, "templates.html");
+    const outputFile = join(fixtureDir, "index.html");
+
+    // Step 1: render shadow DOM via fast-build CLI using config file
+    execFileSync(
+        process.execPath,
+        [fastBin, "build", `--config=${configFile}`, ...passthroughArgs],
+        { stdio: "inherit" },
+    );
+
+    // Step 2: inject <f-template> declarations from templates.html before <script>
+    const fTemplates = readFileSync(templatesFile, "utf8").trim();
+    const rawHtml = readFileSync(outputFile, "utf8");
+
+    if (!rawHtml.includes('<script type="module"')) {
+        throw new Error(
+            `Fixture "${fixtureName}": could not find '<script type="module"' in "${outputFile}". Template injection failed.`,
+        );
+    }
+
+    const html = rawHtml.replace(
+        /(\s*)<script type="module"/,
+        `\n${fTemplates}\n$1<script type="module"`,
+    );
+
+    writeFileSync(outputFile, html);
+    process.stdout.write(`Fixture "${fixtureName}" built successfully.\n`);
+}

package/scripts/declarative/build-fixtures.utilities.js

@@ -0,0 +1,101 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Auto-discover fixture directories that contain the required build files
+ * (entry.html, templates.html, state.json, and fast-build.config.json).
+ *
+ * Fixtures are organized in category subdirectories (e.g., bindings/attribute,
+ * directives/repeat). The function scans two levels deep: category directories
+ * at the top level, and fixture directories within each category.
+ *
+ * Each fixture directory must contain a `fast-build.config.json` that
+ * configures the `@microsoft/fast-build` CLI. At minimum the config
+ * should specify `entry`, `state`, `output`, and `templates`. Fixture-
+ * specific options such as `attribute-name-strategy` can also be included.
+ *
+ * @param {string} fixturesDir - Absolute path to the fixtures directory.
+ * @returns {string[]} Sorted array of fixture paths relative to fixturesDir
+ *   (e.g., "bindings/attribute", "directives/repeat").
+ */
+export function discoverFixtures(fixturesDir) {
+    const fixtures = [];
+
+    for (const category of readdirSync(fixturesDir, { withFileTypes: true })) {
+        if (!category.isDirectory()) continue;
+
+        const categoryDir = join(fixturesDir, category.name);
+
+        for (const fixture of readdirSync(categoryDir, { withFileTypes: true })) {
+            if (!fixture.isDirectory()) continue;
+
+            const dir = join(categoryDir, fixture.name);
+            if (
+                existsSync(join(dir, "entry.html")) &&
+                existsSync(join(dir, "templates.html")) &&
+                existsSync(join(dir, "state.json")) &&
+                existsSync(join(dir, "fast-build.config.json"))
+            ) {
+                fixtures.push(`${category.name}/${fixture.name}`);
+            }
+        }
+    }
+
+    return fixtures.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Extract `<f-template name="X">` elements from an HTML string.
+ * Returns an array of `{ name, content }` objects where `content`
+ * is the inner HTML of the `<template>` child. When the `<template>`
+ * element carries host-binding attributes (e.g. `@click`, `?disabled`),
+ * those are preserved by wrapping the content in a `<template>` tag.
+ * @param {string} html - Raw HTML containing `<f-template>` elements.
+ * @returns {{ name: string, content: string }[]}
+ */
+export function extractFTemplates(html) {
+    const results = [];
+    const regex =
+        /<f-template\s+name="([^"]+)">\s*<template([^>]*)>([\s\S]*?)<\/template>\s*<\/f-template>/g;
+    let match;
+    while ((match = regex.exec(html)) !== null) {
+        const name = match[1];
+        const attrs = match[2].trim();
+        const inner = match[3].trim();
+
+        if (attrs.length > 0) {
+            results.push({
+                name,
+                content: `<template ${attrs}>${inner}</template>`,
+            });
+        } else {
+            results.push({ name, content: inner });
+        }
+    }
+    return results;
+}
+
+/**
+ * Convert FAST template directives to webui syntax.
+ *
+ * - `<f-when value="{{expr}}">` → `<if condition="expr">`
+ * - `</f-when>` → `</if>`
+ * - `<f-repeat value="{{item in list}}" ...>` → `<for each="item in list" ...>`
+ * - `</f-repeat>` → `</for>`
+ *
+ * @param {string} html - Template HTML using FAST directive syntax.
+ * @returns {string} Template HTML using webui directive syntax.
+ */
+export function convertToWebuiSyntax(html) {
+    return html
+        .replace(
+            /<f-when\s+value="{{([\s\S]*?)}}"\s*>/g,
+            (_, expr) => `<if condition="${expr.trim()}">`,
+        )
+        .replace(/<\/f-when>/g, "</if>")
+        .replace(
+            /<f-repeat\s+value="{{([\s\S]*?)}}"([^>]*)>/g,
+            (_, expr, rest) => `<for each="${expr.trim()}"${rest}>`,
+        )
+        .replace(/<\/f-repeat>/g, "</for>");
+}

package/scripts/measure-sizes.js

@@ -0,0 +1,219 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { brotliCompressSync, gzipSync } from "node:zlib";
+import { build } from "esbuild";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const rootImportPath = "@microsoft/fast-element";
+const fastElementImportPath = "@microsoft/fast-element/fast-element.js";
+const updatesImportPath = "@microsoft/fast-element/updates.js";
+const observableImportPath = "@microsoft/fast-element/observable.js";
+const attrImportPath = "@microsoft/fast-element/attr.js";
+const childrenImportPath = "@microsoft/fast-element/children.js";
+const refImportPath = "@microsoft/fast-element/ref.js";
+const slottedImportPath = "@microsoft/fast-element/slotted.js";
+const volatileImportPath = "@microsoft/fast-element/volatile.js";
+const whenImportPath = "@microsoft/fast-element/when.js";
+const htmlImportPath = "@microsoft/fast-element/html.js";
+const repeatImportPath = "@microsoft/fast-element/repeat.js";
+const cssImportPath = "@microsoft/fast-element/css.js";
+const declarativeImportPath = "@microsoft/fast-element/declarative.js";
+const hydrationImportPath = "@microsoft/fast-element/hydration.js";
+const arrayObserverImportPath = "@microsoft/fast-element/array-observer.js";
+const observerMapImportPath = "@microsoft/fast-element/observer-map.js";
+const attributeMapImportPath = "@microsoft/fast-element/attribute-map.js";
+
+const namedExports = [{ name: "FASTElement", importPath: fastElementImportPath }];
+
+const measuredExports = [
+    {
+        name: "Updates",
+        export: "Updates",
+        importPath: updatesImportPath,
+    },
+    {
+        name: "Observable",
+        export: "Observable",
+        importPath: observableImportPath,
+    },
+    {
+        name: "observable",
+        export: "observable",
+        importPath: observableImportPath,
+    },
+    {
+        name: "attr",
+        export: "attr",
+        importPath: attrImportPath,
+    },
+    {
+        name: "children",
+        export: "children",
+        importPath: childrenImportPath,
+    },
+    {
+        name: "ref",
+        export: "ref",
+        importPath: refImportPath,
+    },
+    {
+        name: "slotted",
+        export: "slotted",
+        importPath: slottedImportPath,
+    },
+    {
+        name: "volatile",
+        export: "volatile",
+        importPath: volatileImportPath,
+    },
+    {
+        name: "when",
+        export: "when",
+        importPath: whenImportPath,
+    },
+    {
+        name: "html",
+        export: "html",
+        importPath: htmlImportPath,
+    },
+    {
+        name: "repeat",
+        export: "repeat",
+        importPath: repeatImportPath,
+    },
+    {
+        name: "css",
+        export: "css",
+        importPath: cssImportPath,
+    },
+    {
+        name: "enableHydration",
+        export: "enableHydration",
+        importPath: hydrationImportPath,
+    },
+    {
+        name: "declarativeTemplate",
+        export: "declarativeTemplate",
+        importPath: declarativeImportPath,
+    },
+    {
+        name: "ArrayObserver",
+        export: "ArrayObserver",
+        importPath: arrayObserverImportPath,
+    },
+    {
+        name: "observerMap",
+        export: "observerMap",
+        importPath: observerMapImportPath,
+    },
+    {
+        name: "attributeMap",
+        export: "attributeMap",
+        importPath: attributeMapImportPath,
+    },
+];
+
+function formatExportLabel(name, importPath) {
+    return `${name} (${importPath})`;
+}
+
+function formatBytes(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    return `${(bytes / 1024).toFixed(2)} KB`;
+}
+
+function measureBuffer(buffer) {
+    const gzip = gzipSync(buffer);
+    const brotli = brotliCompressSync(buffer);
+    return {
+        minified: buffer.length,
+        gzip: gzip.length,
+        brotli: brotli.length,
+    };
+}
+
+async function measureExport(exportName, importPath = rootImportPath) {
+    const contents = `import { ${exportName} } from "${importPath}";
+export { ${exportName} };
+`;
+
+    const result = await build({
+        stdin: {
+            contents,
+            resolveDir: packageRoot,
+            loader: "ts",
+        },
+        bundle: true,
+        minify: true,
+        format: "esm",
+        write: false,
+        treeShaking: true,
+    });
+
+    const code = Buffer.from(result.outputFiles[0].contents);
+    return measureBuffer(code);
+}
+
+async function measureCore() {
+    const coreBundle = path.resolve(packageRoot, "dist/fast-element.min.js");
+    const buffer = readFileSync(coreBundle);
+    return measureBuffer(buffer);
+}
+
+async function main() {
+    const results = [];
+
+    // Measure CDN rollup bundle
+    const core = await measureCore();
+    results.push({ name: "CDN Rollup Bundle", ...core });
+
+    // Measure each named export in parallel
+    const exportResults = await Promise.all(
+        namedExports.map(async ({ name, importPath }) => {
+            const sizes = await measureExport(name, importPath);
+            return { name: formatExportLabel(name, importPath), ...sizes };
+        }),
+    );
+    results.push(...exportResults);
+
+    // Measure each root export in parallel
+    const measuredResults = await Promise.all(
+        measuredExports.map(
+            async ({ name, export: exportName, importPath = rootImportPath }) => {
+                const sizes = await measureExport(exportName, importPath);
+                return { name: formatExportLabel(name, importPath), ...sizes };
+            },
+        ),
+    );
+    results.push(...measuredResults);
+
+    // Generate markdown table
+    const lines = [
+        "# Export Sizes",
+        "",
+        "Bundle sizes for `@microsoft/fast-element` exports.",
+        "",
+        "| Export | Minified | Gzip | Brotli |",
+        "|--------|----------|------|--------|",
+    ];
+
+    for (const { name, minified, gzip, brotli } of results) {
+        lines.push(
+            `| ${name} | ${formatBytes(minified)} | ${formatBytes(gzip)} | ${formatBytes(brotli)} |`,
+        );
+    }
+
+    lines.push("");
+
+    const outputPath = path.resolve(packageRoot, "SIZES.md");
+    writeFileSync(outputPath, lines.join("\n"));
+    console.log(`Bundle sizes written to ${outputPath}`);
+}
+
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

package/scripts/run-api-extractor.js

@@ -1,7 +1,7 @@
-import path from "path";
-import fs from "fs";
-import { fileURLToPath } from 'url';
-import { Extractor, ExtractorConfig } from '@microsoft/api-extractor';
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Extractor, ExtractorConfig } from "@microsoft/api-extractor";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -10,17 +10,37 @@ export const exportPaths = [
     {
         path: "./context.js",
         docsFolder: "context",
-        configPath: path.resolve(__dirname, "../api-extractor.context.json")
+        configPath: path.resolve(__dirname, "../api-extractor.context.json"),
+    },
+    {
+        path: "./declarative.js",
+        docsFolder: "declarative",
+        configPath: path.resolve(__dirname, "../api-extractor.declarative.json"),
     },
     {
         path: "./di.js",
         docsFolder: "di",
-        configPath: path.resolve(__dirname, "../api-extractor.di.json")
-    }
+        configPath: path.resolve(__dirname, "../api-extractor.di.json"),
+    },
+    {
+        path: "./hydration.js",
+        docsFolder: "hydration",
+        configPath: path.resolve(__dirname, "../api-extractor.hydration.json"),
+    },
+    {
+        path: "./styles.js",
+        docsFolder: "styles",
+        configPath: path.resolve(__dirname, "../api-extractor.styles.json"),
+    },
+    {
+        path: "./arrays.js",
+        docsFolder: "arrays",
+        configPath: path.resolve(__dirname, "../api-extractor.arrays.json"),
+    },
 ];
 
-(function() {
-    exportPaths.forEach((exportPath) => {
+(function () {
+    exportPaths.forEach(exportPath => {
         const docsFolder = path.resolve(__dirname, `../docs/${exportPath.docsFolder}`);
         // Create folders in the docs directory
         if (!fs.existsSync(docsFolder)) {
@@ -31,20 +51,19 @@ export const exportPaths = [
         const extractorConfig = ExtractorConfig.loadFileAndPrepare(exportPath.configPath);
 
         // Invoke API Extractor
-        const extractorResult = Extractor.invoke(
-            extractorConfig,
-            {
-                // Equivalent to the "--local" command-line parameter
-                localBuild: process.argv[2] !== "ci",
-            }
-        );
+        const extractorResult = Extractor.invoke(extractorConfig, {
+            // Equivalent to the "--local" command-line parameter
+            localBuild: process.argv[2] !== "ci",
+        });
 
         if (extractorResult.succeeded) {
-            console.log(`API Extractor completed successfully for ${exportPath.configPath}`);
-          } else {
+            console.log(
+                `API Extractor completed successfully for ${exportPath.configPath}`,
+            );
+        } else {
             console.error(
-              `API Extractor completed with ${extractorResult.errorCount} errors` +
-                ` and ${extractorResult.warningCount} warnings for ${exportPath.configPath}`
+                `API Extractor completed with ${extractorResult.errorCount} errors` +
+                    ` and ${extractorResult.warningCount} warnings for ${exportPath.configPath}`,
             );
         }
     });

package/test/declarative/fixtures/README.md

@@ -0,0 +1,72 @@
+# Fixtures
+
+Fixtures are organized into category subdirectories:
+
+| Category | Description |
+|---|---|
+| [`bindings/`](./bindings/README.md) | Various binding types (attribute, content, event, dot-syntax, host). |
+| [`scenarios/`](./scenarios/README.md) | Complex scenarios with edge cases involving multiple features. |
+| [`directives/`](./directives/README.md) | Attribute and element directives (`f-repeat`, `f-when`, `f-ref`, etc.). |
+| [`extensions/`](./extensions/README.md) | Additional functionality that augments the core behavior (attribute maps, observer maps). |
+| [`ecosystem/`](./ecosystem/README.md) | Other ecosystem APIs (errors, lifecycle, performance). |
+
+Each fixture contains the following contents:
+
+```
+<category>/<fixture-name>/
+├── <fixture-name>.spec.ts - Playwright tests
+├── entry.html - Entry template with root custom elements (input to build-fixtures.js)
+├── fast-build.config.json - Build configuration for @microsoft/fast-build
+├── index.html - Pre-rendered HTML page served by Vite (generated by build-fixtures.js)
+├── main.ts - Component definition and setup
+├── state.json - Initial state passed to the server-side renderer
+└── templates.html - Declarative f-template definitions
+```
+
+Fixtures are auto-discovered by the Vite config in `../vite.config.ts`. To add a new fixture, create a new directory within the appropriate category with the files above — no other changes are needed.
+
+## Hydration readiness
+
+Fixtures that exercise prerendered Declarative Shadow DOM should enable
+hydration explicitly and set a global flag in the `hydrationComplete()` callback
+so Playwright tests can wait for the element to be fully interactive before
+asserting. The standard pattern is:
+
+1. **In `main.ts`**, call `enableHydration()` before elements connect:
+
+    ```ts
+    import { enableHydration } from "@microsoft/fast-element/hydration.js";
+
+    enableHydration({
+        hydrationComplete() {
+            (window as any).hydrationCompleted = true;
+        },
+    });
+    ```
+
+    Per-element callbacks belong on `declarativeTemplate(callbacks)`. Map
+    behavior belongs in define extensions such as `attributeMap()` and
+    `observerMap()`.
+
+2. **In the spec file**, create the wait **before** navigation so the listener is registered before the page starts loading:
+
+    ```ts
+    const hydrationCompleted = page.waitForFunction(
+        () => (window as any).hydrationCompleted === true,
+    );
+    await page.goto("/fixtures/<fixture-name>/");
+    await hydrationCompleted;
+    ```
+
+    Place this around every `page.goto()` call — including inside `test.beforeEach` hooks — to prevent assertions from running before hydration finishes.
+
+## Entry HTML attribute guidelines
+
+The `entry.html` file defines the root custom elements that the server-side renderer processes. When writing attribute bindings on root elements, follow these conventions:
+
+- **Same-name complex bindings are unnecessary.** Attributes like `list="{{list}}"` where `list` is an array or object are redundant — non-primitive values are automatically stripped from the rendered opening tag, and state propagation already provides the value to the element's template. Omit these attributes.
+- **Rename bindings should be avoided.** Prefer naming state properties to match the attribute name the element expects. When a rename such as `foo="{{bar}}"` is removed, ensure `state.json` includes a property named `foo` with the contents of `bar` so the value is available via state propagation.
+- **Property bindings (`:attr`) for renames are acceptable** when multiple instances of the same element in a fixture need different values for the same property (e.g., `:items="{{emptyItems}}"` and `:items="{{singleItem}}"` on separate elements).
+- **Primitive same-name bindings are fine.** Attributes like `type="{{type}}"` where the value is a string, number, or boolean are rendered onto the opening tag and may be needed for `@attr`-based element initialization.
+
+For a complete guide on creating fixtures — including how to write each file, component patterns, and spec examples — see [WRITING_FIXTURES.md](./WRITING_FIXTURES.md).