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

package/docs/styles/api-report.api.md

@@ -1,135 +0,0 @@
-## API Report File for "@microsoft/fast-element"
-
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
-
-```ts
-
-// @public
-export type ComposableStyles = string | ElementStyles | CSSStyleSheet;
-
-// @public
-export type Constructable<T = {}> = {
-    new (...args: any[]): T;
-};
-
-// @public
-export type ConstructibleStyleStrategy = {
-    new (styles: (string | CSSStyleSheet)[]): StyleStrategy;
-};
-
-// @public
-export interface CSSDirective {
-    createCSS(): ComposableStyles;
-}
-
-// @public
-export const CSSDirective: Readonly<{
-    getForInstance: (object: any) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
-    getByType: (key: Function) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
-    define<TType extends Constructable<CSSDirective>>(type: any): TType;
-}>;
-
-// @public
-export function cssDirective(): (type: Constructable<CSSDirective>) => void;
-
-// @public
-export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective> = Constructable<CSSDirective>> {
-    readonly type: TType;
-}
-
-// @public
-export class ElementStyles {
-    constructor(styles: ReadonlyArray<ComposableStyles>);
-    // @internal (undocumented)
-    addStylesTo(target: StyleTarget): void;
-    // @internal (undocumented)
-    isAttachedTo(target: StyleTarget): boolean;
-    static normalize(styles: ComposableStyles | ComposableStyles[] | undefined): ElementStyles | undefined;
-    // @internal (undocumented)
-    removeStylesFrom(target: StyleTarget): void;
-    static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
-    get strategy(): StyleStrategy;
-    // (undocumented)
-    readonly styles: ReadonlyArray<ComposableStyles>;
-    static readonly supportsAdoptedStyleSheets: boolean;
-    withStrategy(Strategy: ConstructibleStyleStrategy): this;
-}
-
-// @public
-export interface ExecutionContext<TParent = any> {
-    readonly event: Event;
-    eventDetail<TDetail>(): TDetail;
-    eventTarget<TTarget extends EventTarget>(): TTarget;
-    index: number;
-    readonly isEven: boolean;
-    readonly isFirst: boolean;
-    readonly isInMiddle: boolean;
-    readonly isLast: boolean;
-    readonly isOdd: boolean;
-    length: number;
-    parent: TParent;
-    parentContext: ExecutionContext<TParent>;
-}
-
-// @public
-export const ExecutionContext: Readonly<{
-    default: ExecutionContext<any>;
-    getEvent(): Event | null;
-    setEvent(event: Event | null): void;
-}>;
-
-// @public
-export interface ExpressionController<TSource = any, TParent = any> {
-    readonly context: ExecutionContext<TParent>;
-    readonly isBound: boolean;
-    onUnbind(behavior: {
-        unbind(controller: ExpressionController<TSource, TParent>): any;
-    }): void;
-    readonly source: TSource;
-    readonly sourceLifetime?: SourceLifetime;
-}
-
-// @public
-export interface HostBehavior<TSource = any> {
-    addedCallback?(controller: HostController<TSource>): void;
-    connectedCallback?(controller: HostController<TSource>): void;
-    disconnectedCallback?(controller: HostController<TSource>): void;
-    removedCallback?(controller: HostController<TSource>): void;
-}
-
-// @public
-export interface HostController<TSource = any> extends ExpressionController<TSource> {
-    addBehavior(behavior: HostBehavior<TSource>): void;
-    addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
-    readonly isConnected: boolean;
-    mainStyles: ElementStyles | null;
-    removeBehavior(behavior: HostBehavior<TSource>, force?: boolean): void;
-    removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
-}
-
-// @public
-export const SourceLifetime: Readonly<{
-    readonly unknown: undefined;
-    readonly coupled: 1;
-}>;
-
-// @public
-export type SourceLifetime = (typeof SourceLifetime)[keyof typeof SourceLifetime];
-
-// @public
-export interface StyleStrategy {
-    addStylesTo(target: StyleTarget): void;
-    removeStylesFrom(target: StyleTarget): void;
-}
-
-// @public
-export interface StyleTarget extends Pick<Node, "getRootNode"> {
-    adoptedStyleSheets?: CSSStyleSheet[];
-    append(styles: HTMLStyleElement): void;
-    querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;
-    removeChild(styles: HTMLStyleElement): void;
-}
-
-// (No @packageDocumentation comment for this package)
-
-```

package/playwright.config.ts

@@ -1,26 +0,0 @@
-import { defineConfig, devices } from "@playwright/test";
-
-export default defineConfig({
-    testDir: ".",
-    testMatch: "**/*.pw.spec.ts",
-    retries: 3,
-    projects: [
-        {
-            name: "chromium",
-            use: { ...devices["Desktop Chrome"] },
-        },
-        {
-            name: "firefox",
-            use: { ...devices["Desktop Firefox"] },
-        },
-        {
-            name: "webkit",
-            use: { ...devices["Desktop Safari"] },
-        },
-    ],
-    webServer: {
-        command: "npm run test-server",
-        port: 5173,
-        reuseExistingServer: true,
-    },
-});

package/playwright.declarative.config.ts

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

package/playwright.declarative.webui.config.ts

@@ -1,20 +0,0 @@
-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

@@ -1,135 +0,0 @@
-#!/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

@@ -1,49 +0,0 @@
-#!/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

@@ -1,101 +0,0 @@
-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>");
-}