feat(web-components): add SSR support via Declarative Shadow DOM modules

change/@fluentui-web-components-ff6dd466-4b60-4451-ab21-3929917fa50a.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat(web-components): add SSR support via Declarative Shadow DOM modules",
+  "packageName": "@fluentui/web-components",
+  "email": "863023+radium-v@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

package.json

@@ -74,8 +74,9 @@
     "@microsoft/eslint-plugin-sdl": "1.0.1",
     "@microsoft/fast-build": "0.6.0",
     "@microsoft/fast-element": "2.10.4",
-    "@microsoft/fast-test-harness": "0.1.0",
-    "@microsoft/focusgroup-polyfill": "^1.4.1",
+    "@microsoft/fast-html": "1.0.0-alpha.53",
+    "@microsoft/fast-test-harness": "0.3.0",
+    "@microsoft/focusgroup-polyfill": "1.5.0",
     "@microsoft/load-themed-styles": "1.10.26",
     "@microsoft/loader-load-themed-styles": "2.0.17",
     "@microsoft/tsdoc": "0.15.1",

packages/web-components/package.json

@@ -46,17 +46,21 @@
     "./theme/*.js": "./dist/esm/theme/*.js",
     "./*/base.js": "./dist/esm/*/*.base.js",
     "./*/define.js": "./dist/esm/*/define.js",
+    "./*/define-async.js": "./dist/esm/*/define-async.js",
     "./*/definition.js": "./dist/esm/*/*.definition.js",
     "./*/options.js": "./dist/esm/*/*.options.js",
     "./*/styles.js": "./dist/esm/*/*.styles.js",
+    "./*/styles.css": "./dist/esm/*/*.styles.css",
     "./*/template.js": "./dist/esm/*/*.template.js",
+    "./*/template.html": "./dist/esm/*/*.template.html",
     "./*/index.js": "./dist/esm/*/index.js",
     "./*.js": "./dist/esm/*/define.js",
     "./custom-elements.json": "./custom-elements.json",
     "./package.json": "./package.json"
   },
   "sideEffects": [
     "define.*",
+    "define-async.*",
     "define-all.*",
     "index-rollup.*",
     "index-all-rollup.*",
@@ -75,7 +79,11 @@
     "compile:benchmark": "rollup -c rollup.bench.js",
     "clean": "node ./scripts/clean dist",
     "generate-api": "api-extractor run --local",
-    "build": "yarn compile && yarn rollup -c && yarn generate-api && yarn analyze",
+    "build": "yarn compile && yarn build:rollup && yarn build:ssr && yarn generate-api && yarn analyze",
+    "build:ssr:templates": "fast-test-harness generate-templates --tag-prefix=fluent",
+    "build:ssr:styles": "fast-test-harness generate-stylesheets",
+    "build:ssr": "yarn build:ssr:templates && yarn build:ssr:styles",
+    "build:rollup": "rollup -c",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "format": "prettier -w src/**/*.{ts,html} src/*.{ts,html} --ignore-path ../../.prettierignore",
@@ -106,8 +114,14 @@
   },
   "peerDependencies": {
     "@microsoft/fast-element": "^2.0.0",
+    "@microsoft/fast-html": "^1.0.0-alpha.53",
     "@microsoft/focusgroup-polyfill": "^1.4.1"
   },
+  "peerDependenciesMeta": {
+    "@microsoft/fast-html": {
+      "optional": true
+    }
+  },
   "beachball": {
     "disallowedChangeTypes": [
       "major",

packages/web-components/playwright.config.ts

@@ -1,10 +1,42 @@
 import defaultConfig from '@microsoft/fast-test-harness/playwright.config.mjs';
-import { defineConfig } from '@playwright/test';
+import { defineConfig, devices } from '@playwright/test';
 
 const CI = process.env.CI === 'true';
 
+// Duplicate each browser project across CSR and SSR rendering modes so a
+// single `playwright test` run exercises both. Per-test overrides
+// (e.g. `test.use({ ssr: true })`) still take precedence over the
+// project-level value.
+//
+// TODO: Remove this local axis once the equivalent change lands in
+// @microsoft/fast-test-harness/playwright.config.mjs.
+const browsers = [
+  { name: 'chromium', use: devices['Desktop Chrome'] },
+  { name: 'firefox', use: devices['Desktop Firefox'] },
+  {
+    name: 'webkit',
+    use: {
+      ...devices['Desktop Safari'],
+      deviceScaleFactor: 1,
+    },
+  },
+];
+
+const modes = [
+  { suffix: 'csr', ssr: false },
+  { suffix: 'ssr', ssr: true },
+];
+
+const projects = browsers.flatMap(browser =>
+  modes.map(mode => ({
+    name: `${browser.name}-${mode.suffix}`,
+    use: { ...browser.use, ssr: mode.ssr },
+  })),
+);
+
 export default defineConfig({
   ...defaultConfig,
+  projects,
   reporter: CI ? 'github' : 'list',
   testMatch: 'src/**/*.spec.ts',
 });

packages/web-components/src/accordion-item/accordion-item.definition-async.ts

@@ -0,0 +1,15 @@
+import type { PartialFASTElementDefinition } from '@microsoft/fast-element';
+import { tagName } from './accordion-item.options.js';
+
+/**
+ * The async definition configuration for the fluent-accordion-item element.
+ *
+ * @public
+ * @remarks
+ * This is used in server-side rendering (SSR) scenarios where the template
+ * is provided as a deferred option to be hydrated later.
+ */
+export const definition: PartialFASTElementDefinition = {
+  name: tagName,
+  templateOptions: 'defer-and-hydrate',
+};

packages/web-components/src/accordion-item/define-async.ts

@@ -0,0 +1,5 @@
+import { RenderableFASTElement } from '@microsoft/fast-html';
+import { definition } from './accordion-item.definition-async.js';
+import { AccordionItem } from './accordion-item.js';
+
+RenderableFASTElement(AccordionItem).defineAsync(definition);

packages/web-components/src/accordion/accordion.definition-async.ts

@@ -0,0 +1,15 @@
+import { type PartialFASTElementDefinition } from '@microsoft/fast-element';
+import { tagName } from './accordion.options.js';
+
+/**
+ * The async definition configuration for the fluent-accordion element.
+ *
+ * @public
+ * @remarks
+ * This is used in server-side rendering (SSR) scenarios where the template
+ * is provided as a deferred option to be hydrated later.
+ */
+export const declarativeDefinition: PartialFASTElementDefinition = {
+  name: tagName,
+  templateOptions: 'defer-and-hydrate',
+} as const;

packages/web-components/src/accordion/accordion.ts

@@ -110,7 +110,7 @@ export class Accordion extends FASTElement {
    */
   private setItems = (): void => {
     waitForConnectedDescendants(this, () => {
-      if (this.slottedAccordionItems.length === 0) {
+      if (!this.slottedAccordionItems?.length) {
         return;
       }
 

packages/web-components/src/accordion/define-async.ts

@@ -0,0 +1,5 @@
+import { RenderableFASTElement } from '@microsoft/fast-html';
+import { declarativeDefinition } from './accordion.definition-async.js';
+import { Accordion } from './accordion.js';
+
+RenderableFASTElement(Accordion).defineAsync(declarativeDefinition);

packages/web-components/src/anchor-button/anchor-button.definition-async.ts

@@ -0,0 +1,15 @@
+import type { PartialFASTElementDefinition } from '@microsoft/fast-element';
+import { tagName } from './anchor-button.options.js';
+
+/**
+ * The async definition configuration for the fluent-anchor-button element.
+ *
+ * @public
+ * @remarks
+ * This is used in server-side rendering (SSR) scenarios where the template
+ * is provided as a deferred option to be hydrated later.
+ */
+export const definition: PartialFASTElementDefinition = {
+  name: tagName,
+  templateOptions: 'defer-and-hydrate',
+};

packages/web-components/src/anchor-button/anchor-button.spec.ts

@@ -172,9 +172,11 @@ test.describe('Anchor Button', () => {
 
     await fastPage.setTemplate({ attributes: { href: expectedUrl } });
 
+    expect(page.url()).not.toMatch(expectedUrl);
+
     await element.click();
 
-    await expect(page).toHaveURL(expectedUrl);
+    expect(page.url()).toMatch(expectedUrl);
   });
 
   test('should emit a single click event when clicked', async ({ fastPage, page }) => {
@@ -197,8 +199,9 @@ test.describe('Anchor Button', () => {
   });
 
   test('should navigate to the provided url when clicked while pressing the `Control` key on Windows or `Meta` on Mac', async ({
-    fastPage,
     context,
+    fastPage,
+    page,
   }) => {
     const { element } = fastPage;
 
@@ -212,7 +215,11 @@ test.describe('Anchor Button', () => {
 
     const newPage = await newPagePromise;
 
-    await expect(newPage).toHaveURL(expectedUrl);
+    expect(page.url()).not.toMatch(expectedUrl);
+
+    expect(newPage.url()).toMatch(expectedUrl);
+
+    await newPage.close();
   });
 
   test('should navigate to the provided url when `Enter` is pressed via keyboard', async ({ fastPage, page }) => {
@@ -226,12 +233,13 @@ test.describe('Anchor Button', () => {
 
     await element.press('Enter');
 
-    await expect(page).toHaveURL(expectedUrl);
+    expect(page.url()).toMatch(expectedUrl);
   });
 
   test('should navigate to the provided url when `ctrl` and `Enter` are pressed via keyboard', async ({
-    fastPage,
     context,
+    fastPage,
+    page,
   }) => {
     const { element } = fastPage;
 
@@ -249,6 +257,10 @@ test.describe('Anchor Button', () => {
 
     const newPage = await newPagePromise;
 
-    await expect(newPage).toHaveURL(expectedUrl);
+    expect(page.url()).not.toMatch(expectedUrl);
+
+    expect(newPage.url()).toMatch(expectedUrl);
+
+    await newPage.close();
   });
 });

packages/web-components/src/anchor-button/define-async.ts

@@ -0,0 +1,5 @@
+import { RenderableFASTElement } from '@microsoft/fast-html';
+import { definition } from './anchor-button.definition-async.js';
+import { AnchorButton } from './anchor-button.js';
+
+RenderableFASTElement(AnchorButton).defineAsync(definition);

packages/web-components/src/avatar/avatar.definition-async.ts

@@ -0,0 +1,15 @@
+import type { PartialFASTElementDefinition } from '@microsoft/fast-element';
+import { tagName } from './avatar.options.js';
+
+/**
+ * The async definition configuration for the fluent-avatar element.
+ *
+ * @public
+ * @remarks
+ * This is used in server-side rendering (SSR) scenarios where the template
+ * is provided as a deferred option to be hydrated later.
+ */
+export const definition: PartialFASTElementDefinition = {
+  name: tagName,
+  templateOptions: 'defer-and-hydrate',
+};

packages/web-components/src/avatar/avatar.spec.ts

@@ -142,6 +142,7 @@ test.describe('Avatar', () => {
 
         // eslint-disable-next-line playwright/no-conditional-in-test
         if (color !== AvatarColor.colorful) {
+          // eslint-disable-next-line playwright/no-conditional-expect
           await expect.soft(element).toHaveAttribute('data-color', color);
         }
       });

packages/web-components/src/avatar/define-async.ts

@@ -0,0 +1,5 @@
+import { RenderableFASTElement } from '@microsoft/fast-html';
+import { definition } from './avatar.definition-async.js';
+import { Avatar } from './avatar.js';
+
+RenderableFASTElement(Avatar).defineAsync(definition);

packages/web-components/src/badge/badge.definition-async.ts

@@ -0,0 +1,15 @@
+import type { PartialFASTElementDefinition } from '@microsoft/fast-element';
+import { tagName } from './badge.options.js';
+
+/**
+ * The async definition configuration for the fluent-badge element.
+ *
+ * @public
+ * @remarks
+ * This is used in server-side rendering (SSR) scenarios where the template
+ * is provided as a deferred option to be hydrated later.
+ */
+export const definition: PartialFASTElementDefinition = {
+  name: tagName,
+  templateOptions: 'defer-and-hydrate',
+};

packages/web-components/src/badge/define-async.ts

@@ -0,0 +1,5 @@
+import { RenderableFASTElement } from '@microsoft/fast-html';
+import { definition } from './badge.definition-async.js';
+import { Badge } from './badge.js';
+
+RenderableFASTElement(Badge).defineAsync(definition);

packages/web-components/src/button/button.definition-async.ts

@@ -0,0 +1,15 @@
+import type { PartialFASTElementDefinition } from '@microsoft/fast-element';
+import { tagName } from './button.options.js';
+
+/**
+ * The async definition configuration for the fluent-button element.
+ *
+ * @public
+ * @remarks
+ * This is used in server-side rendering (SSR) scenarios where the template
+ * is provided as a deferred option to be hydrated later.
+ */
+export const definition: PartialFASTElementDefinition = {
+  name: tagName,
+  templateOptions: 'defer-and-hydrate',
+};

packages/web-components/src/button/button.spec.ts

@@ -1,3 +1,4 @@
+import type { InitialTemplateAttributes } from '@microsoft/fast-test-harness/fixtures/csr-fixture.js';
 import { expect, test } from '../../test/playwright/index.js';
 import { tagName } from './button.options.js';
 
@@ -262,10 +263,17 @@ test.describe('Button', () => {
     await expect(notFocusable).not.toBeFocused();
   });
 
-  test('should focus the element when the `autofocus` attribute is present', async ({ fastPage }) => {
+  test('should focus the element when the `autofocus` attribute is present', async ({ fastPage, ssr }) => {
     const { element } = fastPage;
 
-    await fastPage.setTemplate({ attributes: { autofocus: true } });
+    const attributes: InitialTemplateAttributes = { autofocus: true };
+
+    if (ssr) {
+      // the host element needs to be focusable for autofocus to work on the server, so we need to set tabindex="0"
+      attributes.tabindex = '0';
+    }
+
+    await fastPage.setTemplate({ attributes });
 
     await expect(element).toBeFocused();
   });

packages/web-components/src/button/define-async.ts

@@ -0,0 +1,5 @@
+import { RenderableFASTElement } from '@microsoft/fast-html';
+import { definition } from './button.definition-async.js';
+import { Button } from './button.js';
+
+RenderableFASTElement(Button).defineAsync(definition);