diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 97282b0ecf5..86531d45f58 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -12,7 +12,7 @@ applyTo: '**/*' ## Repository Overview -FAST (`@microsoft/fast`) is a Microsoft open-source monorepo for building W3C-standards-compliant Web Components. The core package is `@microsoft/fast-element` ā€” a lightweight, performant Web Component authoring library. Additional packages provide routing and declarative HTML support. +FAST (`@microsoft/fast`) is a Microsoft open-source monorepo for building W3C-standards-compliant Web Components. The core package is `@microsoft/fast-element` ā€” a lightweight, performant Web Component authoring library with a declarative HTML entrypoint. Additional packages provide routing plus declarative build and test tooling. ## Packages @@ -20,8 +20,7 @@ Each package includes a DESIGN.md file, read that to gain a general understandin | Package | Status | Purpose | |---|---|---| -| `@microsoft/fast-element` | Stable (v2) | Core Web Component library | -| `@microsoft/fast-html` | Alpha | Declarative HTML parser | +| `@microsoft/fast-element` | Stable (v2) | Core Web Component library, including declarative HTML via `@microsoft/fast-element/declarative.js` | | `@microsoft/fast-router` | Alpha | Web Component router | | `@microsoft/fast-build` | Prerelease | Declarative HTML server side renderer | | `@microsoft/fast-test-harness` | Prerelease | Testing utilities for FASTElement components | diff --git a/.github/skills/shipping/SKILL.md b/.github/skills/shipping/SKILL.md index a5b59ef85db..09d99dcbb2f 100644 --- a/.github/skills/shipping/SKILL.md +++ b/.github/skills/shipping/SKILL.md @@ -48,7 +48,7 @@ Use [conventional commit](https://www.conventionalcommits.org/) format for PR ti Common types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`. Examples: -- `feat: add shadow DOM support to fast-html parser` +- `feat: add shadow DOM support to declarative templates` - `fix: resolve memory leak in template binding` - `chore: update dev dependencies` diff --git a/.github/skills/testing/SKILL.md b/.github/skills/testing/SKILL.md index fe3dab72d53..4a30a1dd58f 100644 --- a/.github/skills/testing/SKILL.md +++ b/.github/skills/testing/SKILL.md @@ -27,22 +27,22 @@ All commands are run from the **monorepo root**. Use `-w` to target a specific p |---|---| | Run all tests (all browsers) | `npm run test` | | Run all tests (Chromium only) | `npm run test:chromium` | -| Test a single package (all browsers) | `npm run test -w @microsoft/fast-html` | -| Test a single package (Chromium only) | `npm run test:chromium -w @microsoft/fast-html` | +| Test a single package (all browsers) | `npm run test -w @microsoft/fast-element` | +| Test a single package (Chromium only) | `npm run test:chromium -w @microsoft/fast-element` | | Test changed packages only | `npx lage test:node test:chromium --since origin/main` | #### Interactive / debug workflows -For `@microsoft/fast-html`, these additional scripts are available: +For FAST declarative tests in `@microsoft/fast-element`, these additional scripts are available: | Task | Command | |---|---| -| Playwright UI mode | `npm run test:ui -w @microsoft/fast-html` | -| Start Vite dev server only | `npm run test-server -w @microsoft/fast-html` | -| Dev mode (watch + server) | `npm run dev -w @microsoft/fast-html` | -| Rebuild fixtures | `npm run build:fixtures -w @microsoft/fast-html` | -| Build fixtures with webui | `npm run build:fixtures:webui -w @microsoft/fast-html` | -| Run webui integration tests | `npm run test:webui-integration -w @microsoft/fast-html` | +| Playwright UI mode | `npm run test:ui:declarative -w @microsoft/fast-element` | +| Start Vite dev server only | `npm run test-server:declarative -w @microsoft/fast-element` | +| Dev mode (watch + server) | `npm run dev:declarative -w @microsoft/fast-element` | +| Rebuild fixtures | `npm run build:fixtures -w @microsoft/fast-element` | +| Build fixtures with webui | `npm run build:fixtures:webui -w @microsoft/fast-element` | +| Run webui integration tests | `npm run test:webui-integration -w @microsoft/fast-element` | **Playwright UI mode** (`test:ui`) starts a visual test runner where you can select and debug individual tests, view traces, and inspect DOM snapshots. @@ -80,7 +80,7 @@ A dedicated workflow for validating FAST's integration with `@microsoft/webui`. The workflow builds all packages, installs Playwright Chromium, and runs: ```bash -npm run test:webui-integration -w @microsoft/fast-html +npm run test:webui-integration -w @microsoft/fast-element ``` This builds each fixture with `webui build --plugin=fast`, renders the protocol with the fixture's `state.json`, and runs the same Playwright specs against the webui-rendered output. @@ -105,13 +105,13 @@ FAST tests are [Playwright](https://playwright.dev/) integration tests that run - Fixture tests live inside their fixture directory: `test/fixtures///.spec.ts`. - Source-level tests are co-located next to the code they test: `src//.pw.spec.ts`. -### Writing fixture tests for fast-html +### Writing declarative fixture tests -Fixture tests for `@microsoft/fast-html` are the primary way to verify declarative template features. Each fixture is a self-contained test case with its own HTML, state, templates, and component definitions. +Fixture tests in `@microsoft/fast-element/test/declarative/fixtures` are the primary way to verify declarative template features. Each fixture is a self-contained test case with its own HTML, state, templates, and component definitions. For a complete guide on creating fixtures ā€” including how to write `entry.html`, `state.json`, `templates.html`, `main.ts`, and spec files ā€” see: -šŸ“„ **[Writing Fixtures](../../../packages/fast-html/test/fixtures/WRITING_FIXTURES.md)** +šŸ“„ **[Writing Fixtures](../../../packages/fast-element/test/declarative/fixtures/WRITING_FIXTURES.md)** ### Quick example diff --git a/.github/workflows/ci-webui-integration.yml b/.github/workflows/ci-webui-integration.yml index 25ec5a641cc..2f90b381a41 100644 --- a/.github/workflows/ci-webui-integration.yml +++ b/.github/workflows/ci-webui-integration.yml @@ -47,4 +47,4 @@ jobs: run: npx playwright install --with-deps chromium - name: Run WebUI integration tests - run: npm run test:webui-integration -w @microsoft/fast-html + run: npm run test:webui-integration -w @microsoft/fast-element diff --git a/change/@microsoft-fast-build-61e3e3bd-e227-4449-9ff6-8edc104819d8.json b/change/@microsoft-fast-build-61e3e3bd-e227-4449-9ff6-8edc104819d8.json new file mode 100644 index 00000000000..86f3c8d6f6b --- /dev/null +++ b/change/@microsoft-fast-build-61e3e3bd-e227-4449-9ff6-8edc104819d8.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "Update fast-build documentation to reference the fast-element declarative HTML docs.", + "packageName": "@microsoft/fast-build", + "email": "7559015+janechu@users.noreply.github.com", + "dependentChangeType": "none" +} diff --git a/change/@microsoft-fast-element-59a62261-1a53-4564-bc64-0c9c1982be71.json b/change/@microsoft-fast-element-59a62261-1a53-4564-bc64-0c9c1982be71.json new file mode 100644 index 00000000000..e3f8429818b --- /dev/null +++ b/change/@microsoft-fast-element-59a62261-1a53-4564-bc64-0c9c1982be71.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "Simplify fast-element declarative package documentation and test configuration without changing the published API.", + "packageName": "@microsoft/fast-element", + "email": "7559015+janechu@users.noreply.github.com", + "dependentChangeType": "none" +} diff --git a/change/@microsoft-fast-element-move-declarative-html.json b/change/@microsoft-fast-element-move-declarative-html.json new file mode 100644 index 00000000000..a7142b625e8 --- /dev/null +++ b/change/@microsoft-fast-element-move-declarative-html.json @@ -0,0 +1,7 @@ +{ + "type": "major", + "comment": "Move declarative HTML APIs into @microsoft/fast-element/declarative.js and remove the @microsoft/fast-html package.", + "packageName": "@microsoft/fast-element", + "dependentChangeType": "none", + "email": "7559015+janechu@users.noreply.github.com" +} diff --git a/change/@microsoft-fast-html-1776500147.json b/change/@microsoft-fast-html-1776500147.json deleted file mode 100644 index 6063c56706a..00000000000 --- a/change/@microsoft-fast-html-1776500147.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "prerelease", - "comment": "Remove RenderableFASTElement mixin and defer-hydration/needs-hydration attribute handling. Components extend FASTElement directly and use defineAsync(). The prepare() lifecycle hook is replaced by setting state after connectedCallback. Hydration lifecycle callbacks (hydrationStarted, hydrationComplete) are now managed by TemplateElement.", - "packageName": "@microsoft/fast-html", - "email": "janechu@microsoft.com", - "dependentChangeType": "none" -} diff --git a/change/@microsoft-fast-html-2751da26-46f3-4c7d-ae10-4437c26b800b.json b/change/@microsoft-fast-html-2751da26-46f3-4c7d-ae10-4437c26b800b.json deleted file mode 100644 index fc4bcbc9cf0..00000000000 --- a/change/@microsoft-fast-html-2751da26-46f3-4c7d-ae10-4437c26b800b.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "prerelease", - "comment": "feat: add properties path tree to ObserverMapConfig in fast-html", - "packageName": "@microsoft/fast-html", - "email": "7559015+janechu@users.noreply.github.com", - "dependentChangeType": "none" -} diff --git a/change/@microsoft-fast-html-30f1b1bf-454c-4952-a54c-7a0a5131b741.json b/change/@microsoft-fast-html-30f1b1bf-454c-4952-a54c-7a0a5131b741.json deleted file mode 100644 index 6861e2da194..00000000000 --- a/change/@microsoft-fast-html-30f1b1bf-454c-4952-a54c-7a0a5131b741.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "none", - "comment": "chore: remove @microsoft/fast-ssr", - "packageName": "@microsoft/fast-html", - "email": "7559015+janechu@users.noreply.github.com", - "dependentChangeType": "none" -} diff --git a/change/@microsoft-fast-html-38230c9f-5bd8-405f-8345-520cd1f11c03.json b/change/@microsoft-fast-html-38230c9f-5bd8-405f-8345-520cd1f11c03.json deleted file mode 100644 index 1213288af47..00000000000 --- a/change/@microsoft-fast-html-38230c9f-5bd8-405f-8345-520cd1f11c03.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "prerelease", - "comment": "Remove RenderableFASTElement from benchmarks; replace defineAsync with define in all fixtures", - "packageName": "@microsoft/fast-html", - "email": "7559015+janechu@users.noreply.github.com", - "dependentChangeType": "patch" -} diff --git a/change/@microsoft-fast-html-3d7093a2-e0fd-4abd-b1fa-6c9a9763c0a0.json b/change/@microsoft-fast-html-3d7093a2-e0fd-4abd-b1fa-6c9a9763c0a0.json deleted file mode 100644 index b7dbfa63c43..00000000000 --- a/change/@microsoft-fast-html-3d7093a2-e0fd-4abd-b1fa-6c9a9763c0a0.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "none", - "comment": "refactor: modularize Schema, ObserverMap, and AttributeMap in fast-html", - "packageName": "@microsoft/fast-html", - "email": "7559015+janechu@users.noreply.github.com", - "dependentChangeType": "none" -} diff --git a/change/@microsoft-fast-html-ee5e1a5d-0ff4-46fe-96c9-ed982e93e391.json b/change/@microsoft-fast-html-ee5e1a5d-0ff4-46fe-96c9-ed982e93e391.json deleted file mode 100644 index 293e17774d4..00000000000 --- a/change/@microsoft-fast-html-ee5e1a5d-0ff4-46fe-96c9-ed982e93e391.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "none", - "comment": "chore: update webui to 0.0.10", - "packageName": "@microsoft/fast-html", - "email": "7559015+janechu@users.noreply.github.com", - "dependentChangeType": "none" -} diff --git a/change/@microsoft-fast-html-f5809cff-6821-407a-b563-e4da096fc8d9.json b/change/@microsoft-fast-html-f5809cff-6821-407a-b563-e4da096fc8d9.json deleted file mode 100644 index fe648382b38..00000000000 --- a/change/@microsoft-fast-html-f5809cff-6821-407a-b563-e4da096fc8d9.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "none", - "comment": "refactor: categorize fast-html fixture files into organized subdirectories", - "packageName": "@microsoft/fast-html", - "email": "7559015+janechu@users.noreply.github.com", - "dependentChangeType": "none" -} diff --git a/change/@microsoft-fast-html-fe4f7812-d5d7-40a1-bb1b-31abe4d47aec.json b/change/@microsoft-fast-html-fe4f7812-d5d7-40a1-bb1b-31abe4d47aec.json deleted file mode 100644 index c3db2c5dc6c..00000000000 --- a/change/@microsoft-fast-html-fe4f7812-d5d7-40a1-bb1b-31abe4d47aec.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "prerelease", - "comment": "Update hydration markers to simplified data-free format and replace hardcoded benchmark render functions with WASM-based SSR rendering.", - "packageName": "@microsoft/fast-html", - "email": "7559015+janechu@users.noreply.github.com", - "dependentChangeType": "none" -} diff --git a/package-lock.json b/package-lock.json index 71afa348775..132217aa830 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1525,10 +1525,6 @@ "resolved": "packages/fast-element", "link": true }, - "node_modules/@microsoft/fast-html": { - "resolved": "packages/fast-html", - "link": true - }, "node_modules/@microsoft/fast-router": { "resolved": "packages/fast-router", "link": true @@ -6976,19 +6972,10 @@ "packages/fast-element": { "name": "@microsoft/fast-element", "version": "2.10.4", - "license": "MIT" - }, - "packages/fast-html": { - "name": "@microsoft/fast-html", - "version": "1.0.0-alpha.50", "license": "MIT", "devDependencies": { - "@microsoft/fast-build": "^0.4.0", - "@microsoft/fast-element": "^2.10.4", + "@microsoft/fast-build": "*", "@microsoft/webui": "0.0.10" - }, - "peerDependencies": { - "@microsoft/fast-element": "^2.10.4" } }, "packages/fast-router": { @@ -7017,14 +7004,14 @@ }, "devDependencies": { "@microsoft/fast-build": "*", - "@microsoft/fast-html": "*" + "@microsoft/fast-element": "*" }, "engines": { "node": ">=22.18.0" }, "peerDependencies": { "@microsoft/fast-build": ">=0.4.0 <1.0.0", - "@microsoft/fast-html": ">=1.0.0-alpha.50 <1.0.0", + "@microsoft/fast-element": ">=2.10.4 <3.0.0", "@playwright/test": ">=1.40.0", "vite": ">=7.0.0" }, @@ -7032,7 +7019,7 @@ "@microsoft/fast-build": { "optional": true }, - "@microsoft/fast-html": { + "@microsoft/fast-element": { "optional": true } } @@ -7303,8 +7290,8 @@ "name": "@microsoft/fast-bench", "version": "0.0.0", "dependencies": { - "@microsoft/fast-element": "*", - "@microsoft/fast-html": "*" + "@microsoft/fast-build": "*", + "@microsoft/fast-element": "*" } }, "sites/website": { diff --git a/packages/fast-build/README.md b/packages/fast-build/README.md index 2fa7dc0966a..07cd968cf61 100644 --- a/packages/fast-build/README.md +++ b/packages/fast-build/README.md @@ -157,4 +157,6 @@ All keys are optional. Only the following keys are allowed: `entry`, `state`, `o ## Template syntax -Template syntax follows the FAST declarative HTML format. See the [`@microsoft/fast-html` README](../fast-html/README.md) for full documentation on bindings, conditionals, repeats, and directives. +Template syntax follows the FAST declarative HTML format. See the +[`@microsoft/fast-element` declarative documentation](../fast-element/DECLARATIVE_HTML.md) +for full documentation on bindings, conditionals, repeats, and directives. diff --git a/packages/fast-html/DESIGN.md b/packages/fast-element/DECLARATIVE_DESIGN.md similarity index 84% rename from packages/fast-html/DESIGN.md rename to packages/fast-element/DECLARATIVE_DESIGN.md index 25f700ca145..92877af1fc4 100644 --- a/packages/fast-html/DESIGN.md +++ b/packages/fast-element/DECLARATIVE_DESIGN.md @@ -1,6 +1,10 @@ -# fast-html Package Design +# Declarative HTML Design -This document is intended for contributors who want to understand the internal architecture of `@microsoft/fast-html`. It covers the package's purpose, core concepts, data flow, and its integration with `@microsoft/fast-element`. +This document is intended for contributors who want to understand the internal +architecture of the declarative runtime in +`@microsoft/fast-element/declarative.js`. It covers the feature's purpose, core +concepts, data flow, and its integration with the rest of +`@microsoft/fast-element`. ## Table of Contents @@ -16,15 +20,18 @@ This document is intended for contributors who want to understand the internal a 10. [Lifecycle](#lifecycle) 11. [Integration with fast-element](#integration-with-fast-element) 12. [Hydration Model](#hydration-model) -13. [Conversion Rules (ast-grep)](#conversion-rules-ast-grep) -14. [Testing Architecture](#testing-architecture) -15. [Further Reading](#further-reading) +13. [Testing Architecture](#testing-architecture) +14. [Further Reading](#further-reading) --- ## Overview -`@microsoft/fast-html` is an **Alpha** declarative HTML parser that lets you write FAST Web Component templates as plain HTML rather than JavaScript `html` tagged template literals. The browser-side JS bundle includes the `` custom element, which parses a declarative template at runtime and attaches it as a `ViewTemplate` to a waiting FAST element definition. +`@microsoft/fast-element/declarative.js` lets you write FAST Web Component +templates as plain HTML rather than JavaScript `html` tagged template literals. +The browser-side JS bundle includes the `` custom element, which +parses a declarative template at runtime and attaches it as a `ViewTemplate` to +a waiting FAST element definition. ```html @@ -155,14 +162,13 @@ All delimiters used by the parser are defined in a single `Syntax` interface and ## Package Structure ``` -packages/fast-html/ +packages/fast-element/ ā”œā”€ā”€ src/ -ā”‚ ā”œā”€ā”€ index.ts # Public barrel ā€” re-exports from components/ -ā”‚ ā”œā”€ā”€ interfaces.ts # Message enum (error codes) -ā”‚ ā”œā”€ā”€ debug.ts # Human-readable debug messages registered with FAST -ā”‚ ā””ā”€ā”€ components/ -ā”‚ ā”œā”€ā”€ index.ts # Component barrel -ā”‚ ā”œā”€ā”€ element.ts # Element utilities +ā”‚ ā”œā”€ā”€ declarative.ts # Public declarative entrypoint +ā”‚ ā””ā”€ā”€ declarative/ +ā”‚ ā”œā”€ā”€ index.ts # Declarative barrel export +ā”‚ ā”œā”€ā”€ interfaces.ts # Message enum (error codes) +ā”‚ ā”œā”€ā”€ debug.ts # Human-readable debug messages registered with FAST ā”‚ ā”œā”€ā”€ template.ts # TemplateElement (), lifecycle orchestration, options ā”‚ ā”œā”€ā”€ template-parser.ts # TemplateParser ā€” converts declarative HTML to ViewTemplate strings/values ā”‚ ā”œā”€ā”€ schema.ts # Schema class ā€” JSON schema builder + schemaRegistry @@ -170,12 +176,10 @@ packages/fast-html/ ā”‚ ā”œā”€ā”€ attribute-map.ts # AttributeMap class + config types (AttributeMapConfig, AttributeMapOption) ā”‚ ā”œā”€ā”€ utilities.ts # Parsing engine, binding resolvers, proxy system ā”‚ ā””ā”€ā”€ syntax.ts # Syntax delimiter constants -ā”œā”€ā”€ rules/ # ast-grep YAML rules for converting html`` ā†’ declarative HTML -ā”œā”€ā”€ rule-tests/ # ast-grep rule test fixtures ā”œā”€ā”€ scripts/ -ā”‚ ā””ā”€ā”€ build-fixtures.js # Builds pre-rendered test fixture HTML via @microsoft/fast-build config files +ā”‚ ā””ā”€ā”€ declarative/ # Fixture build + webui integration scripts ā””ā”€ā”€ test/ - ā””ā”€ā”€ fixtures/ # One directory per feature, each with spec + index.html + main.ts + ā””ā”€ā”€ declarative/fixtures/ # One directory per feature, each with spec + index.html + main.ts ``` ### Module dependency direction @@ -209,7 +213,7 @@ import { type AttributeMapConfig, type JSONSchema, type CachedPathMap, -} from "@microsoft/fast-html"; +} from "@microsoft/fast-element/declarative.js"; ``` Primary exports intended for application code: @@ -419,7 +423,9 @@ flowchart LR G --> H["when user= is set:\nassignObservables checks schema.$observe\nā†’ Proxy wraps observed paths only\ndeep mutations ā†’ Observable.notify"] ``` -For a deep dive into the schema structure, context tracking, and proxy system see [SCHEMA_OBSERVER_MAP.md](./SCHEMA_OBSERVER_MAP.md). +For a deep dive into the schema structure, context tracking, and proxy system +see +[DECLARATIVE_SCHEMA_OBSERVER_MAP.md](./DECLARATIVE_SCHEMA_OBSERVER_MAP.md). ### `$observe` flag on schema nodes @@ -502,15 +508,19 @@ sequenceDiagram | `elementDidHydrate(source)` | After an instance is fully hydrated | | `hydrationComplete()` | Once, after all prerendered elements have completed hydration | -For usage examples see [RENDERING_LIFECYCLE.md](./RENDERING_LIFECYCLE.md). +For usage examples see +[DECLARATIVE_RENDERING_LIFECYCLE.md](./DECLARATIVE_RENDERING_LIFECYCLE.md). --- ## Integration with fast-element -`@microsoft/fast-html` is a thin orchestration layer on top of `@microsoft/fast-element`. It does not re-implement any reactive primitives; it converts declarative HTML syntax into the same data structures that `html` tagged templates produce. +The declarative runtime is a thin orchestration layer on top of +`@microsoft/fast-element`. It does not re-implement any reactive primitives; it +converts declarative HTML syntax into the same data structures that `html` +tagged templates produce. -| fast-element primitive | How fast-html uses it | +| fast-element primitive | How the declarative runtime uses it | |---|---| | `FASTElement` | Base class for both `TemplateElement` and user components (components extend `FASTElement` directly) | | `FASTElementDefinition.register()` | Deferred element registration ā€” element waits for its template | @@ -563,35 +573,23 @@ Connection gating is handled by the template-pending guard in `ElementController ``` -For detailed examples see [RENDERING.md](./RENDERING.md). - ---- - -## Conversion Rules (ast-grep) - -The `rules/` directory contains `.yml` rules for [ast-grep](https://ast-grep.github.io/) that partially automate converting `@microsoft/fast-element` tagged-template components to declarative HTML syntax. - -| Rule file | Converts | -|---|---| -| `tag-function-to-template-literal.yml` | `` html`...` `` ā†’ plain template string | -| `member-expression.yml` | `${x => x.prop}` ā†’ `{{prop}}` | -| `attribute-directives.yml` | `${slotted("prop")}` ā†’ `f-slotted="{prop}"` | -| `call-expression-with-event-argument.yml` | `${(x,c) => x.handler(c.event)}` ā†’ `@event="{handler($e)}"` | - -See [rules/README.md](./rules/README.md) for usage instructions. +For detailed examples see +[DECLARATIVE_RENDERING.md](./DECLARATIVE_RENDERING.md). --- ## Testing Architecture -Each feature is verified by a **Playwright** integration test against a live Vite dev server. The `test/fixtures/` directory contains one subdirectory per feature: +Each feature is verified by a **Playwright** integration test against a live +Vite dev server. The `test/declarative/fixtures/` directory contains one +subdirectory per feature: ``` -test/fixtures// +test/declarative/fixtures// ā”œā”€ā”€ .spec.ts # Playwright test ā”œā”€ā”€ entry.html # Entry template with root custom elements ā”œā”€ā”€ fast-build.config.json # Build configuration for @microsoft/fast-build -ā”œā”€ā”€ index.html # Pre-rendered page (GENERATED by scripts/build-fixtures.js ā€” do not edit) +ā”œā”€ā”€ index.html # Pre-rendered page (GENERATED by scripts/declarative/build-fixtures.js ā€” do not edit) ā”œā”€ā”€ main.ts # Component definition + TemplateElement setup ā”œā”€ā”€ state.json # Initial state for server-side rendering ā””ā”€ā”€ templates.html # Declarative definitions @@ -599,28 +597,53 @@ test/fixtures// Fixtures are auto-discovered by scanning for directories 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. -For fixtures that use SSR-style pre-rendered HTML, `scripts/build-fixtures.js` invokes `@microsoft/fast-build` with `--config` pointing to each fixture's `fast-build.config.json` to generate `index.html` from the configured source files. +For fixtures that use SSR-style pre-rendered HTML, +`scripts/declarative/build-fixtures.js` invokes `@microsoft/fast-build` with +`--config` pointing to each fixture's `fast-build.config.json` to generate +`index.html` from the configured source files. ### WebUI Integration Tests A separate integration test suite validates that `@microsoft/webui` can build and render the same fixture templates that `@microsoft/fast-build` processes. This is split into two steps: -1. **Build** (`npm run build:fixtures:webui`) ā€” runs `scripts/build-fixtures-with-webui.js`, which extracts `` elements, builds each fixture with `webui build --plugin=fast`, renders the protocol with `state.json`, and writes the output alongside `main.ts` and assets to `temp/integrations/webui/fixtures/`. -2. **Test** (`npm run test:webui-integration`) ā€” builds the fixtures, then runs the same Playwright specs against the webui-rendered output served by a Vite dev server on port 5174 (configured in `playwright.webui.config.ts`). +1. **Build** (`npm run build:fixtures:webui`) ā€” runs + `scripts/declarative/build-fixtures-with-webui.js`, which extracts + `` elements, builds each fixture with `webui build --plugin=fast`, + renders the protocol with `state.json`, and writes the output alongside + `main.ts` and assets to `temp/integrations/webui/fixtures/`. +2. **Test** (`npm run test:webui-integration`) ā€” builds the fixtures, then runs + the same Playwright specs against the webui-rendered output served by a Vite + dev server on port 5174 (configured in + `playwright.declarative.webui.config.ts`). Run locally with `npm run test:webui-integration` or via the `ci-webui-integration.yml` GitHub Action on PRs and pushes to `main`. #### Skipped tests -Some tests are conditionally skipped when running under the webui integration config. The `playwright.webui.config.ts` sets `process.env.FAST_WEBUI_INTEGRATION = "true"`, and individual tests check this variable with `test.skip()` to opt out of cases that exercise known differences between `fast-build` and `webui` rendering: +Some tests are conditionally skipped when running under the webui integration +config. The `playwright.declarative.webui.config.ts` file sets +`process.env.FAST_WEBUI_INTEGRATION = "true"`, and individual tests check this +variable with `test.skip()` to opt out of cases that exercise known differences +between `fast-build` and `webui` rendering: - **`errors.spec.ts` ā€” "throws an error when no template element is present"**: webui does not render `` elements that lack a `