@microsoft/fast-test-harness 0.1.0 → 0.3.0

package/README.md

@@ -4,6 +4,11 @@
 
 The `fast-test-harness` package is a Playwright testing harness for FAST Element web components with CSR and SSR support.
 
+## Requirements
+
+- Node.js 22.18 or later
+- Playwright 1.56 or later
+
 ## Installation
 
 To install `fast-test-harness` using `npm`:
@@ -12,6 +17,21 @@ To install `fast-test-harness` using `npm`:
 npm install --save-dev @microsoft/fast-test-harness
 ```
 
+## Test directory setup
+
+The harness serves a Vite dev server from a `test/` directory in your project. CSR and SSR modes use different entry points from the same directory.
+
+```
+test/
+├── index.html              # CSR: loads main.ts
+├── ssr.html                # SSR: template with comment placeholders
+├── vite.config.ts          # Vite config (shared by both modes)
+└── src/
+    ├── main.ts             # CSR: registers components, applies theme
+    ├── entry-client.ts     # SSR: registers components for hydration
+    └── entry-server.ts     # SSR: exports render() for fixture generation
+```
+
 ## Writing tests
 
 Import `test` and `expect` from the harness. Configure the component tag name with `test.use()`, then call `fastPage.setTemplate()` in each test to render it.
@@ -67,21 +87,6 @@ await expect(element).toHaveCustomState("checked");
 | `waitFor` | `string[]` | `[]` | Additional elements to wait for before testing |
 | `ssr` | `boolean` | `false` | Use SSR mode (or set `PLAYWRIGHT_TEST_SSR=true`) |
 
-## Test directory setup
-
-The harness serves a Vite dev server from a `test/` directory in your project. CSR and SSR modes use different entry points from the same directory.
-
-```
-test/
-├── index.html              # CSR: loads main.ts
-├── ssr.html                # SSR: template with comment placeholders
-├── vite.config.ts          # Vite config (shared by both modes)
-└── src/
-    ├── main.ts             # CSR: registers components, applies theme
-    ├── entry-client.ts     # SSR: registers components for hydration
-    └── entry-server.ts     # SSR: exports render() for fixture generation
-```
-
 ### CSR files
 
 **`index.html`** loads a script that registers your components:
@@ -248,7 +253,7 @@ CLI flags take precedence over environment variables.
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `tagPrefix` | `string` | Tag name prefix for custom elements (e.g., `"fluent"`, `"mai"`) |
+| `tagPrefix` | `string` | Tag name prefix for custom elements (e.g., `"fluent"`, `"contoso"`) |
 | `packageName` | `string?` | Monolithic package name — scans subdirectories for component artifacts. Mutually exclusive with `components`. |
 | `components` | `ComponentRegistration[]?` | Explicit list of per-component packages. Mutually exclusive with `packageName`. |
 | `distDir` | `string?` | Artifact directory relative to the package root (default: `"dist/esm"`). Only used with `packageName`. |
@@ -258,10 +263,11 @@ CLI flags take precedence over environment variables.
 
 | Specifier | Contents |
 |-----------|----------|
-| `@microsoft/fast-test-harness` | `test`, `expect`, `CSRFixture`, `SSRFixture`, `createSSRRenderer`, build utilities |
+| `@microsoft/fast-test-harness` | `test`, `expect`, `CSRFixture`, `SSRFixture`, `toHaveCustomState`, `installDomShim`, `createSSRRenderer` |
+| `@microsoft/fast-test-harness/build/*.js` | `installDomShim`, `generateStylesheets`, `generateFTemplates`, `generateWebuiTemplates`, `definitionAsyncResolver`, `shadowOptionsToAttributes`, `ShadowOptionsResolver` |
+| `@microsoft/fast-test-harness/fixtures/*.js` | `CSRFixture`, `SSRFixture`, `toHaveCustomState`, extended `test` and `expect` |
+| `@microsoft/fast-test-harness/ssr/render.js` | `createSSRRenderer`, `renderTemplate`, `buildEntryHtml`, `buildState` |
 | `@microsoft/fast-test-harness/server.mjs` | `startServer` |
-| `@microsoft/fast-test-harness/ssr/render.js` | `createSSRRenderer`, `ComponentRegistration`, `RenderResult`, `SSRRendererOptions` |
-| `@microsoft/fast-test-harness/build/*.js` | `installDomShim`, `generateStylesheets`, `generateFTemplates`, `generateWebuiTemplates` |
 | `@microsoft/fast-test-harness/playwright.config.mjs` | Shared Playwright configuration |
 | `@microsoft/fast-test-harness/vite.config.mjs` | Shared Vite configuration |
 | `@microsoft/fast-test-harness/public/*` | Static assets (base CSS) |

package/dist/dts/build/generate-templates.d.ts

@@ -45,7 +45,37 @@ export interface GenerateFTemplatesOptions {
      * Optional formatter function applied to generated HTML before writing.
      */
     format?: (html: string, filePath: string) => string | Promise<string>;
+    /**
+     * Resolves shadow DOM options for a given template module path.
+     * Returns a `shadowOptions` object (e.g. `{ delegatesFocus: true }`) or
+     * `undefined` if the component has no special shadow options.
+     *
+     * Defaults to {@link definitionAsyncResolver}, which loads a companion
+     * `*.definition-async.js` module next to each template. Set to `null`
+     * to disable shadow options resolution.
+     *
+     * @default definitionAsyncResolver
+     */
+    resolveShadowOptions?: ShadowOptionsResolver | null;
 }
+/**
+ * A function that resolves shadow DOM options for a template module.
+ * Receives the absolute path to the compiled `*.template.js` file and
+ * returns shadow options or `undefined`.
+ */
+export type ShadowOptionsResolver = (templateJsPath: string) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+/**
+ * Convention-based resolver that loads a companion `*.definition-async.js`
+ * module next to the template module and returns its `shadowOptions`.
+ *
+ * For a template at `dist/textarea/textarea.template.js`, this looks for
+ * `dist/textarea/textarea.definition-async.js`.
+ *
+ * This is the default resolver used by {@link generateFTemplates} and
+ * {@link generateWebuiTemplates} when `resolveShadowOptions` is not
+ * specified.
+ */
+export declare function definitionAsyncResolver(templateJsPath: string): Promise<Record<string, unknown> | undefined>;
 export interface ViewTemplate {
     html: string | HTMLTemplateElement;
     factories: Record<string, Factory>;
@@ -64,6 +94,11 @@ interface Factory {
  * f-template HTML string.
  */
 export declare function convertTemplate(viewTemplate: ViewTemplate, componentName: string): string | null;
+/**
+ * Convert a `shadowOptions` object (e.g. `{ delegatesFocus: true }`) into
+ * DSD template attribute entries (e.g. `{ shadowrootdelegatesfocus: "" }`).
+ */
+export declare function shadowOptionsToAttributes(shadowOptions: Record<string, unknown> | undefined): Record<string, string>;
 export declare function generateFTemplates(options?: GenerateFTemplatesOptions): Promise<void>;
 export {};
 //# sourceMappingURL=generate-templates.d.ts.map

package/dist/dts/build/generate-templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-templates.d.ts","sourceRoot":"","sources":["../../../src/build/generate-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA8BH,MAAM,WAAW,yBAAyB;IACtC;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,UAAU,OAAO;IACb,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,WAAW,CAAC,EAAE;QACV,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;KACrC,CAAC;CACL;AAmFD;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,YAAY,EAAE,YAAY,EAC1B,aAAa,EAAE,MAAM,GACtB,MAAM,GAAG,IAAI,CA4Hf;AAED,wBAAsB,kBAAkB,CACpC,OAAO,GAAE,yBAA8B,GACxC,OAAO,CAAC,IAAI,CAAC,CAkEf"}
+{"version":3,"file":"generate-templates.d.ts","sourceRoot":"","sources":["../../../src/build/generate-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA8BH,MAAM,WAAW,yBAAyB;IACtC;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtE;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAChC,cAAc,EAAE,MAAM,KACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;AAExF;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CACzC,cAAc,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAY9C;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,UAAU,OAAO;IACb,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,WAAW,CAAC,EAAE;QACV,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;KACrC,CAAC;CACL;AAmFD;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,YAAY,EAAE,YAAY,EAC1B,aAAa,EAAE,MAAM,GACtB,MAAM,GAAG,IAAI,CA4Hf;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACrC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACnD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBxB;AAED,wBAAsB,kBAAkB,CACpC,OAAO,GAAE,yBAA8B,GACxC,OAAO,CAAC,IAAI,CAAC,CAgFf"}

package/dist/dts/build/generate-webui-templates.d.ts

@@ -14,9 +14,10 @@
  * ```ts
  * import { generateWebuiTemplates } from "@microsoft/fast-test-harness/build/generate-webui-templates.js";
  *
- * await generateWebuiTemplates({ cwd: process.cwd(), tagPrefix: "mai" });
+ * await generateWebuiTemplates({ cwd: process.cwd(), tagPrefix: "contoso" });
  * ```
  */
+import { type ShadowOptionsResolver } from "./generate-templates.js";
 export interface GenerateWebuiTemplatesOptions {
     /**
      * Root directory of the package. Defaults to `process.cwd()`.
@@ -49,6 +50,18 @@ export interface GenerateWebuiTemplatesOptions {
      * Optional formatter function applied to generated HTML before writing.
      */
     format?: (html: string, filePath: string) => string | Promise<string>;
+    /**
+     * Resolves shadow DOM options for a given template module path.
+     * Returns a `shadowOptions` object (e.g. `{ delegatesFocus: true }`) or
+     * `undefined` if the component has no special shadow options.
+     *
+     * Defaults to {@link definitionAsyncResolver}, which loads a companion
+     * `*.definition-async.js` module next to each template. Set to `null`
+     * to disable shadow options resolution.
+     *
+     * @default definitionAsyncResolver
+     */
+    resolveShadowOptions?: ShadowOptionsResolver | null;
 }
 export declare function generateWebuiTemplates(options?: GenerateWebuiTemplatesOptions): Promise<void>;
 //# sourceMappingURL=generate-webui-templates.d.ts.map

package/dist/dts/build/generate-webui-templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-webui-templates.d.ts","sourceRoot":"","sources":["../../../src/build/generate-webui-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgBH,MAAM,WAAW,6BAA6B;IAC1C;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACzE;AAuED,wBAAsB,sBAAsB,CACxC,OAAO,GAAE,6BAAkC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAmEf"}
+{"version":3,"file":"generate-webui-templates.d.ts","sourceRoot":"","sources":["../../../src/build/generate-webui-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,OAAO,EAGH,KAAK,qBAAqB,EAG7B,MAAM,yBAAyB,CAAC;AAQjC,MAAM,WAAW,6BAA6B;IAC1C;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtE;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACvD;AA4CD,wBAAsB,sBAAsB,CACxC,OAAO,GAAE,6BAAkC,GAC5C,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/dist/dts/fixtures/csr-fixture.d.ts

@@ -1,6 +1,17 @@
 import type { Locator, Page } from "@playwright/test";
 export type ThemeTokens = Record<string, string | number | boolean>;
+/**
+ * The initial attributes for the fixture's template, where boolean attributes are
+ * represented as `true` and omitted when `false`. This allows for a more intuitive
+ * configuration of boolean attributes in the template options.
+ */
 export type InitialTemplateAttributes = Record<string, string | true>;
+/**
+ * The attributes for the fixture's template, where boolean attributes can be represented as `true`
+ * or `false`. When `true`, the attribute will be included without a value (e.g., `disabled`), and
+ * when `false`, the attribute will be omitted entirely. This type is used for updating the
+ * template, allowing for both adding and removing boolean attributes.
+ */
 export type TemplateAttributes = Record<string, string | boolean>;
 /**
  * The options for configuring the fixture's template.
@@ -9,6 +20,10 @@ export type InitialTemplateOptions = {
     attributes?: InitialTemplateAttributes;
     innerHTML?: string;
 };
+/**
+ * The options for updating the fixture's template, where `attributes` can include boolean values to
+ * add or remove attributes from the element.
+ */
 export type FixtureOptions = Omit<InitialTemplateOptions, "attributes"> & {
     attributes?: TemplateAttributes;
 };
@@ -36,6 +51,19 @@ export declare class CSRFixture {
     protected readonly innerHTML: string;
     /**
      * Additional custom elements to wait for before running the test.
+     *
+     * @remarks
+     * This is useful for fixtures that depend on multiple custom elements being defined
+     * and stable before the test can run. By specifying additional tag names here, the
+     * fixture will wait for these elements to be defined before proceeding. Ensure that
+     * any elements specified here are included on the page and properly defined to
+     * prevent test timeouts.
+     *
+     * @example
+     * test.use({
+     *     tagName: "fast-dropdown",
+     *     waitFor: ["fast-listbox", "fast-option"],
+     * });
      */
     protected readonly waitFor: string[];
     /**

package/dist/dts/fixtures/csr-fixture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csr-fixture.d.ts","sourceRoot":"","sources":["../../../src/fixtures/csr-fixture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEpE,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACjC,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,sBAAsB,EAAE,YAAY,CAAC,GAAG;IACtE,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACnC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,GAAG,MAAM,CAAC;AAEhE;;GAEG;AACH,qBAAa,UAAU;aA8BC,IAAI,EAAE,IAAI;IA7B9B;;OAEG;IACH,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAErC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAErC;;;;;;;OAOG;IACH,YACoB,IAAI,EAAE,IAAI,EAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,MAAM,EAAO,EAMzB;IAED;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E;IAED;;;;OAIG;IACG,IAAI,CAAC,GAAG,GAAE,MAAY,iBAE3B;IAED;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CASpD;IAED;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBtE;IAED;;;;;OAKG;IACH,UAAgB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAqBhD;IAED;;;;;;OAMG;IACG,cAAc,CAChB,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAuBf;IAED;;;;;;OAMG;IACG,oBAAoB,CACtB,OAAO,GAAE,MAAqB,EAC9B,GAAG,QAAQ,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC,CAUf;CACJ"}
+{"version":3,"file":"csr-fixture.d.ts","sourceRoot":"","sources":["../../../src/fixtures/csr-fixture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEpE;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACjC,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,sBAAsB,EAAE,YAAY,CAAC,GAAG;IACtE,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACnC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,GAAG,MAAM,CAAC;AAEhE;;GAEG;AACH,qBAAa,UAAU;aA2CC,IAAI,EAAE,IAAI;IA1C9B;;OAEG;IACH,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAErC;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAErC;;;;;;;OAOG;IACH,YACoB,IAAI,EAAE,IAAI,EAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,MAAM,EAAO,EAMzB;IAED;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E;IAED;;;;OAIG;IACG,IAAI,CAAC,GAAG,GAAE,MAAY,iBAE3B;IAED;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CASpD;IAED;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBtE;IAED;;;;;OAKG;IACH,UAAgB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAqBhD;IAED;;;;;;OAMG;IACG,cAAc,CAChB,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAuBf;IAED;;;;;;OAMG;IACG,oBAAoB,CACtB,OAAO,GAAE,MAAqB,EAC9B,GAAG,QAAQ,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC,CAUf;CACJ"}

package/dist/dts/fixtures/ssr-fixture.d.ts

@@ -11,6 +11,25 @@ export declare class SSRFixture extends CSRFixture {
      * Whether the template has been rendered.
      */
     private templateRendered;
+    /**
+     * The internal reference to the generated fixture URL.
+     */
+    private _url?;
+    /**
+     * The URL of the generated SSR fixture page. This is set after {@link setTemplate}
+     * is called and the page navigates to the generated fixture.
+     */
+    get url(): string | undefined;
+    /**
+     * Creates an instance of the SSRFixture.
+     *
+     * @param page - The Playwright page object.
+     * @param tagName - The tag name of the custom element.
+     * @param innerHTML - The inner HTML of the custom element.
+     * @param waitFor - Additional custom elements to wait for.
+     * @param testId - The test ID for the SSR fixture.
+     * @param testTitle - The test title for the SSR fixture.
+     */
     constructor(page: Page, tagName: string, innerHTML?: string, waitFor?: string[], testId?: string, testTitle?: string);
     /**
      * Buffers style tags added before {@link setTemplate} so they can be

package/dist/dts/fixtures/ssr-fixture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-fixture.d.ts","sourceRoot":"","sources":["../../../src/fixtures/ssr-fixture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,qBAAa,UAAW,SAAQ,UAAU;IAgBlC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAhB/B;;OAEG;IACH,OAAO,CAAC,aAAa,CAA4C;IAEjE;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAS;IAEjC,YACI,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAW,EACtB,OAAO,GAAE,MAAM,EAAO,EACL,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAGtC;IAED;;;;;;;OAOG;IACY,WAAW,CACtB,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAMf;IAED;;;;;;;;;;;OAWG;IACY,WAAW,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoE/E;IAED;;OAEG;IACH,OAAO,CAAC,eAAe;CAqB1B"}
+{"version":3,"file":"ssr-fixture.d.ts","sourceRoot":"","sources":["../../../src/fixtures/ssr-fixture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,qBAAa,UAAW,SAAQ,UAAU;IAuClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAvC/B;;OAEG;IACH,OAAO,CAAC,aAAa,CAA4C;IAEjE;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAS;IAEjC;;OAEG;IACH,OAAO,CAAC,IAAI,CAAC,CAAS;IAEtB;;;OAGG;IACH,IAAW,GAAG,IAAI,MAAM,GAAG,SAAS,CAEnC;IAED;;;;;;;;;OASG;IACH,YACI,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAW,EACtB,OAAO,GAAE,MAAM,EAAO,EACL,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAGtC;IAED;;;;;;;OAOG;IACY,WAAW,CACtB,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAMf;IAED;;;;;;;;;;;OAWG;IACY,WAAW,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqE/E;IAED;;OAEG;IACH,OAAO,CAAC,eAAe;CAqB1B"}

package/dist/dts/ssr/render.d.ts

@@ -21,10 +21,10 @@
  * flat exports.
  * ```ts
  * const { render } = createSSRRenderer({
- *     tagPrefix: "mai",
+ *     tagPrefix: "contoso",
  *     components: [
- *         { name: "button", packageName: "@mai-ui/button" },
- *         { name: "checkbox", packageName: "@mai-ui/checkbox" },
+ *         { name: "button", packageName: "@contoso/button" },
+ *         { name: "checkbox", packageName: "@contoso/checkbox" },
  *     ],
  * });
  * ```
@@ -37,25 +37,25 @@ export interface ComponentRegistration {
     name: string;
     /**
      * The npm package name for this component
-     * (e.g., "@mai-ui/button").
+     * (e.g., "@contoso/button").
      */
     packageName: string;
 }
 export interface SSRRendererOptions {
     /**
-     * Tag name prefix for custom elements (e.g., "fluent", "mai").
+     * Tag name prefix for custom elements (e.g., "fluent", "contoso").
      */
     tagPrefix: string;
     /**
      * The npm package name used to resolve component build artifacts
      * when all components live in subdirectories of a single package
-     * (Fluent-style). Mutually exclusive with `components`.
+     * (monolithic layout). Mutually exclusive with `components`.
      */
     packageName?: string;
     /**
-     * Explicit list of per-component packages (MAI-style). Each entry
-     * maps a component name to its npm package. Mutually exclusive
-     * with `packageName`.
+     * Explicit list of per-component packages. Each entry maps a
+     * component name to its npm package. Mutually exclusive with
+     * `packageName`.
      */
     components?: ComponentRegistration[];
     /**
@@ -82,11 +82,6 @@ export interface RenderResult {
     /** Preload link tags (empty string when using fast-build). */
     preloadLinks: string;
 }
-/**
- * Parse a JavaScript default value string from CEM into a JSON-safe value.
- * @internal
- */
-export declare function parseDefaultValue(raw: string): unknown;
 /**
  * Replace the `{{styles}}` placeholder in an f-template with a
  * stylesheet `<link>` tag. Falls back to injecting after the opening
@@ -117,9 +112,9 @@ export declare function buildState(queryObj: Record<string, string>): Record<str
  *
  * Supports two modes:
  * - **`packageName`**: Scans a monolithic package's dist directory for
- *   components in subdirectories (Fluent-style).
+ *   components in subdirectories (monolithic layout).
  * - **`components`**: Uses an explicit list of per-component packages
- *   with flat exports (MAI-style).
+ *   with flat exports.
  */
 export declare function createSSRRenderer(options: SSRRendererOptions): {
     render: (queryObj: Record<string, string>) => RenderResult;

package/dist/dts/ssr/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/ssr/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAOH,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IAC/B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,UAAU,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAErC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IACzB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACxB;AA4CD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA6BtD;AA0FD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAa1E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAwCvE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsBpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG;IAC5D,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,YAAY,CAAC;CAC9D,CA4IA"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/ssr/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAOH,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IAC/B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,UAAU,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAErC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IACzB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACxB;AAqFD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAa1E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAwCvE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsBpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG;IAC5D,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,YAAY,CAAC;CAC9D,CA6KA"}

package/dist/esm/build/generate-templates.js

@@ -29,6 +29,30 @@ function wrapDefaultExpression(expression) {
 function attributeDirective(name, value) {
     return `${attributeDirectivePrefix}${name}="${wrapClientExpression(value)}"`;
 }
+/**
+ * Convention-based resolver that loads a companion `*.definition-async.js`
+ * module next to the template module and returns its `shadowOptions`.
+ *
+ * For a template at `dist/textarea/textarea.template.js`, this looks for
+ * `dist/textarea/textarea.definition-async.js`.
+ *
+ * This is the default resolver used by {@link generateFTemplates} and
+ * {@link generateWebuiTemplates} when `resolveShadowOptions` is not
+ * specified.
+ */
+export async function definitionAsyncResolver(templateJsPath) {
+    const dir = path.dirname(templateJsPath);
+    const base = path.basename(templateJsPath, ".template.js");
+    const defAsyncPath = path.resolve(dir, `${base}.definition-async.js`);
+    try {
+        const mod = await import(pathToFileURL(defAsyncPath).href);
+        const definition = mod.definition ?? mod.default;
+        return definition?.shadowOptions;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Extract a readable binding expression from a factory's evaluate function.
  */
@@ -195,10 +219,33 @@ export function convertTemplate(viewTemplate, componentName) {
     // so the test harness can substitute it with a <link rel="stylesheet"> at
     // render time. Harness fallback auto-injects if the marker is missing, but
     // emitting it explicitly keeps generated output consistent with hand-authored
-    // f-templates (see MAI core components).
+    // f-templates.
     fInner = fInner.replace(/(<template[^>]*>)/, `$1${stylesMarker}`);
     return `<f-template name="${componentName}" shadowrootmode="open">\n${fInner}\n</f-template>\n`;
 }
+/**
+ * Convert a `shadowOptions` object (e.g. `{ delegatesFocus: true }`) into
+ * DSD template attribute entries (e.g. `{ shadowrootdelegatesfocus: "" }`).
+ */
+export function shadowOptionsToAttributes(shadowOptions) {
+    const attrs = {};
+    if (!shadowOptions) {
+        return attrs;
+    }
+    for (const [key, value] of Object.entries(shadowOptions)) {
+        if (key === "mode") {
+            continue;
+        }
+        const attrName = `shadowroot${key.toLowerCase()}`;
+        if (value === true) {
+            attrs[attrName] = "";
+        }
+        else if (typeof value === "string" && value !== "") {
+            attrs[attrName] = value;
+        }
+    }
+    return attrs;
+}
 export async function generateFTemplates(options = {}) {
     installDomShim();
     const cwd = options.cwd ?? process.cwd();
@@ -220,7 +267,19 @@ export async function generateFTemplates(options = {}) {
             if (!fTemplateHtml) {
                 continue;
             }
+            // Resolve shadow options and inject them into the <f-template> tag.
+            const resolver = options.resolveShadowOptions === null
+                ? undefined
+                : (options.resolveShadowOptions ?? definitionAsyncResolver);
+            const shadowOpts = resolver ? await resolver(jsFilePath) : undefined;
+            const shadowAttrs = shadowOptionsToAttributes(shadowOpts);
             let html = fTemplateHtml;
+            if (Object.keys(shadowAttrs).length > 0) {
+                const extraAttrs = Object.entries(shadowAttrs)
+                    .map(([k, v]) => (v ? ` ${k}="${v}"` : ` ${k}`))
+                    .join("");
+                html = html.replace(/(<f-template[^>]*)(>)/, `$1${extraAttrs}$2`);
+            }
             if (options.format) {
                 try {
                     html = await options.format(html, jsFilePath);
@@ -229,8 +288,9 @@ export async function generateFTemplates(options = {}) {
                     console.warn(styleText(["yellow", "bold"], "⚠"), `Format failed for ${componentName}:`, formatError.message);
                 }
             }
+            const relativeDir = path.relative(distDir, path.dirname(jsFilePath));
             const fTemplatePath = outDir
-                ? path.resolve(outDir, `${componentBaseName}.template.html`)
+                ? path.resolve(outDir, relativeDir, `${componentBaseName}.template.html`)
                 : path.resolve(path.dirname(jsFilePath), `${componentBaseName}.template.html`);
             await mkdir(path.dirname(fTemplatePath), { recursive: true });
             await writeFile(fTemplatePath, html, "utf8");

package/dist/esm/build/generate-webui-templates.js

@@ -14,7 +14,7 @@
  * ```ts
  * import { generateWebuiTemplates } from "@microsoft/fast-test-harness/build/generate-webui-templates.js";
  *
- * await generateWebuiTemplates({ cwd: process.cwd(), tagPrefix: "mai" });
+ * await generateWebuiTemplates({ cwd: process.cwd(), tagPrefix: "contoso" });
  * ```
  */
 import { glob, mkdir, writeFile } from "node:fs/promises";
@@ -23,31 +23,9 @@ import { pathToFileURL } from "node:url";
 import { styleText } from "node:util";
 import { closeExpression, openExpression } from "@microsoft/fast-html/syntax.js";
 import { installDomShim } from "./dom-shim.js";
-import { convertTemplate } from "./generate-templates.js";
+import { convertTemplate, definitionAsyncResolver, shadowOptionsToAttributes, } from "./generate-templates.js";
 const stylesMarker = `${openExpression}styles${closeExpression}`;
 const escapedStylesMarker = new RegExp(stylesMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
-/**
- * Try to load shadow options from a companion `*.definition-async.js`
- * module next to the template module. Returns an object with template
- * attribute strings to add (e.g. `shadowrootdelegatesfocus`).
- */
-async function loadShadowAttributes(templateJsPath) {
-    const dir = path.dirname(templateJsPath);
-    const base = path.basename(templateJsPath, ".template.js");
-    const defAsyncPath = path.resolve(dir, `${base}.definition-async.js`);
-    const attrs = {};
-    try {
-        const mod = await import(pathToFileURL(defAsyncPath).href);
-        const definition = mod.definition ?? mod.default;
-        if (definition?.shadowOptions?.delegatesFocus) {
-            attrs.shadowrootdelegatesfocus = "";
-        }
-    }
-    catch {
-        // No definition-async module or it failed to load — skip.
-    }
-    return attrs;
-}
 /**
  * Transform an f-template string into a webui template by replacing the
  * `<f-template>` wrapper with `<template shadowrootmode="open">` and
@@ -97,7 +75,11 @@ export async function generateWebuiTemplates(options = {}) {
             if (!fTemplateHtml) {
                 continue;
             }
-            const shadowAttrs = await loadShadowAttributes(jsFilePath);
+            const resolver = options.resolveShadowOptions === null
+                ? undefined
+                : (options.resolveShadowOptions ?? definitionAsyncResolver);
+            const shadowOpts = resolver ? await resolver(jsFilePath) : undefined;
+            const shadowAttrs = shadowOptionsToAttributes(shadowOpts);
             let html = fTemplateToWebui(fTemplateHtml, shadowAttrs);
             if (options.format) {
                 try {
@@ -107,8 +89,9 @@ export async function generateWebuiTemplates(options = {}) {
                     console.warn(styleText(["yellow", "bold"], "⚠"), `Format failed for ${componentName}:`, formatError.message);
                 }
             }
+            const relativeDir = path.relative(distDir, path.dirname(jsFilePath));
             const webuiPath = outDir
-                ? path.resolve(outDir, `${componentBaseName}.template-webui.html`)
+                ? path.resolve(outDir, relativeDir, `${componentBaseName}.template-webui.html`)
                 : path.resolve(path.dirname(jsFilePath), `${componentBaseName}.template-webui.html`);
             await mkdir(path.dirname(webuiPath), { recursive: true });
             await writeFile(webuiPath, html, "utf8");

package/dist/esm/fixtures/ssr-fixture.js

@@ -1,5 +1,22 @@
 import { CSRFixture } from "./csr-fixture.js";
 export class SSRFixture extends CSRFixture {
+    /**
+     * The URL of the generated SSR fixture page. This is set after {@link setTemplate}
+     * is called and the page navigates to the generated fixture.
+     */
+    get url() {
+        return this._url;
+    }
+    /**
+     * Creates an instance of the SSRFixture.
+     *
+     * @param page - The Playwright page object.
+     * @param tagName - The tag name of the custom element.
+     * @param innerHTML - The inner HTML of the custom element.
+     * @param waitFor - Additional custom elements to wait for.
+     * @param testId - The test ID for the SSR fixture.
+     * @param testTitle - The test title for the SSR fixture.
+     */
     constructor(page, tagName, innerHTML = "", waitFor = [], testId, testTitle) {
         super(page, tagName, innerHTML, waitFor);
         this.testId = testId;
@@ -86,7 +103,8 @@ export class SSRFixture extends CSRFixture {
         if (!result.url) {
             throw new Error(`Invalid response from server: ${JSON.stringify(result)}`);
         }
-        await this.page.goto(result.url);
+        this._url = result.url;
+        await this.page.goto(this._url);
         await this.waitForStability();
         this.templateRendered = true;
         this.pendingStyles.length = 0;